Reference Guide 


Reference Guide 


* ObjectWindows Classes 
¢ Event-handling Functions 
¢ Dispatch Functions 


{Windows 


com! 
ae 
P= 


* ObjectComponents Classes 


¢ Linking and Embedding Borland 


¢ Automation 


eee: 


Reference Guide 


Borland® 


ObjectWindows” 


Borland International, Inc., 100 Borland Way 
P.O. Box 660001, Scotts Valley, CA 95067-0001 


Borland may have patents and/or pending patent applications covering subject matter in this document. The 
furnishing of this document does not give you any license to these patents. 


COPYRIGHT © 1991, 1994 Borland International. All rights reserved. All Borland products are trademarks or 
registered trademarks of Borland International, Inc. Other brand and product names are trademarks or registered 
trademarks of their respective holders. | | | 


Printed in the U.S.A. 
1EOR1094 


9495969798-9 8 7 6 5432 
HI 


Contents 


Introduction | 1 
What's new in ObjectWindows 2.5......... 1 
Contents of thismanual............... Z 
Typefaces used in thismanual ...... Rees 3 
Conventions used inthismanual ..... og ate 
Part I 
ObjectWindows reference 5 
Chapter 1 
Overview of ObjectWindows 7 
Hierarchy diagram .............-2..-.-. vi 
Using ObjectWindows classes .......... 10 
Base classes .. 0... eee ee eee 10 
Window management classes .......... 11 
Frame windows ..........-.+6-.26-. 11 
Decorated windows................ 11 
Common dialogs.................. 11 
Contols:2 ks ooh wa, es oe TO 12 
Cad Sele ac Sieg BU ee: b Aiea ihe woe 12 
DVICTVUG i. ise to's cS eID ee ee en tee bq eee. 13 
Module management classes........... 13 
DGe/ View Classesis é. 4c. gh tobe a are Gk 13 
Printer? Classes)‘ <his06 wa, bee. Bae ws Sone Se 14 
Graphics classess 34:6 8 asi sad Sie ee Bobs 14 
DCC aSSOS 5-5 55) 56.550 i ai Bile es Bx ced ws 14 
GDUCIASSCS i be gtar es, & a see aes, oes 14 
Validator Classes e163 e450, a) he ap ae wt 14 
Exception handling classes ............ 15 
Command enabling classes............ 15 
ObjectSupport library classes. .......... 15 
ObjectWindows Libraries. ............ 16 
Compiler options for building and using 
ObjectWindows libraries. ............ 17 
Building ObjectWindows libraries. ...... 18 
Using ObjectWindows libraries ........ 18 
The ObjectWindows header files... ...... 19 
The ObjectWindows resource files. ....... 23 
The ObjectWindows datatypes ......... 24 
Chapter 2 
ObjectWindows library reference 25 
TBird class[sample] ................ 25 
TYPE CeCRINONS 6. 0.6.G.5 4 es ahem SE ea 25 
Public datamembers................ 26 
Public constructor and destructor........ 26 
Public member functions ............. 26 


Protected datamembers ............. 27 

Protected constructors............... he 

Protected member functions........... Pay 

Response table entries............... 27 
BF_xxxx button flag constants .......... 28 
BN_xxxx button message constants ....... 28 
CBN_xxxx combo box message constants . . . 28 
CM_xxxx editconstants.............. 29 
CM_xxxx edit fileconstants............ 29 
CM_xxxx edit replace constants ......... 30 
CM_xxxx edit view constants........... 30 
CM_xxxx MDI constants. ............. 31 
DECLARE RESPONSE TABLE macro..... 31 
DEFINE_APP_ DICTIONARY macro ...... 31 
DEFINE_DOC_TEMPLATE_CLASS macro . . 32 
DEFINE_RESPONSE_ TABLE macros...... 32 . 
DLGC_xxxx dialog control message 

CONSIAING: a70.5 Sw Ma We Se ook ae BSS 33 
dmxxxx document manager mode 
CONSEAINS 4:0 4 oie Sea Sw. oe be Ged How od 33 

dnxxxx document message constants...... 34 
dtxxxx document template constants ...... 34 
END_RESPONSE_TABLE macro ........ 35 
EN_xxxx edit message constants......... 35 
BV SOOOTACIOS: 6 ctw. & 2 Bard ee we ae 4 36 
Factory template classes.............. 36 
GetApplicationObject function. ......... 40 . 
GetWindowPtr function. ............. 40 
ID_xxxx fileconstants ............... 40 
ID_xxxx printer constants... .......... 41 
IDA_xxxx accelerator ID constants. ....... 41 
IDA_xxxx OLE accelerator ID constants ... . 41 
IDM_xxxx menuID constants .......... 4] 
IDM_xxxx OLE menu ID constants ....... Al 
IDS_xxxx edit view ID constants. ........ 42 
IDS_Mode constants ................ 42 
IDS_xxxx document string ID constants. . .. . 42 
IDS_xxxx edit fileID constants.......... 43 
IDS_xxxx exception message constants ..... 43 
IDS_xxxx listview ID constants.......... 44 
IDS_xxxx printer string ID constants... .... 4A 
[IDS_xxxx validator ID constants ......... 44 
IDW_MDICLIENT constant............ 45 
IDW_MDIFIRSTCHILD constant ........ 45 


LangXxxx ID constants... ............ 45 


LBN_xxxx list box message constant 


ImParent constant................ .. 46 
LongMulDiv function........ No Geeta 46 
MAX_RSRC_ERROR_STRING constant... . 46 | 
- MB_Xxxx message constants..........:. 46 
NBits function.................00.4 47 
NColors function. ....... eee ee 47 
ofxxxx document openenum........... 48 
-pfxxxx property attribute constants. ...... 48 
~_BUILDOWLDLL macro ............. 49 
-OWLCLASS macro. ..............0. 49 
—OWLDATA macro. ................ 49 
JOWLDLL macro. . 2. ee oe eee eee AO 
-OWLFAR macro. ............ Sas ote i 40 
OWLEFARVTABLE macro ............ 50 
-OWLFASTTHIS macro.............. 50 
~ OWLFUNC macro ................ 50 
OWLGetVersion function............. 50 
- SB_Xxxx scrollbar constants ........... 51 
shxxxx document sharingenum......... 51 
TActionFunc typedef......... ee oe 
TActionMemFunc typedef ............ ol 
TAny PMS ty Pedel 4 3-0-0 ada ti ogre Ged 51 
TAnyDispatcher typedef..............52 
TAppDictionary class ............... 52 
Type definitions... ................ 53 
Public constructor and destructor. ....... 54. 
— Publicmember functions ............. 54 
TApplication class .............000. 55 
Public datamembers................ 55 
Type Cehminonss 2:25:45 web oe ows hm ee 56 
Public constructor and destructor ........ 56 
Public member functions ............. 57 
Protected datamembers.............. 61. 
~. Protected member functions ........... 62 
TApplication ‘TXInvalidMainWindow class . . 63 
‘Public constructor .. 2... .......000.0. 63 
Public member functions ............. 63 
_ TAutoFactory<> class... ........000. 64 
Public member functions ............. 64 
TBandInfo struct ...............000. 65 
‘TBitmap class... 2.6... eee ee 65 
Public constructors...............04 65 
Public member functions ............. 66 
Protected constructor.............00. 68 
Protected member functions .......... 68 
Operators ....... ee ee ee 68 
TBitmapGadget class. bi es contd: ee ok eee aes 68 
Public constructor and destructor........ 68 


Public member functions. ........:... 
Protected member functions. .......... 69 
TBitSet class 2. 62ers HO Saved PEER A 69 
Public constructors ................ 69 
Public member functions............. 70 
TBIVbxLibrary class ...........00005 71 
Public constructor and eae ee yee 71 
PPISTUISICIASS <5:3: S45) Alp btde Sa we he ok 71 
Public constructors ................ 71 
Public member functions............. 72 
A BUttOnCIASS «50 eee oe Ba ie Boe No oe ee 72 
Publicdatamembers ............... 72 
_ Publicconstructors ................ 73 
Protected datamember.............. 73 
Protected member functions. .......... 73 
Response table entries............... 74 
TButtonGadget class................ 74 
Type definitions .................. 75 
Public constructor and destructor. ..... oe 7 D* 
Public member functions............. 75 
Protected datamembers ............. 76 
Protected member functions........... 77 
TButtonGadgetEnabler class ........... 79 
Public constructor................. 79 
Protected datamember.............. 80 
Public member functions. ............ 80 
TCetArray Class: 4 2a ob telat eink eae: 80 
Public constructors and destructor ....... 80 
Public member functions............. 81 
Protected datamembers ............. 82 
TCharSet class. ............0000008 82 
Publicconstructors ..............0- 82 
Public member function ............. 83 
TCheckBox class. .............0.000- 83 
Public datamember........06........ 83 
Public constructors ..............004 83 
Public member functions. ............ 84 
Protected member functions........... 85 
Response table entries... ............ 86 
TChooseColorDialog class........... . . 86 
- Publicconstructors .....:........... 86 
Public member function ............. 86 
Publicdatamembers............... 86 
Protected member functions........... 87 
Response table entries............... 87 
TChooseColorDialog::TData class ........ 87 
Public datamembers ............... 87 | 
TChooseFontDialog class ............. 88 
Public constructor. ...........00005 88 
Protected datamembers ............. 89 
Protected member functions........... 89 


il 


Response table entries... ........0.... 89 
TChooseFontDialog::TData class......... 89 
Public datamembers................ 90 
TChentDC: Class: 2:0 006 6 este 6 ee Gr RN Bw 91 
Public constructors. .............200. 91 
TChipboard Class: «6.2 bw ee ede 92 
Public destructor...............00. 93 
Public datamembers................ 93 
Public member functions ............. 93 
Protected datamembers.............. 96 
Protected constructor................ 97 
TClipboardViewer Class.............. oF 
Protected datamember .............. 97 
Protected constructors............... 97 
Protected member functions ........... 97 
Response table entries... ............ 98 
TOO Class go 15. a doa Seo Sls BS Se Se Sek 98 
Public constructors...............0. 98 
Public datamembers................ 99 
Public member functions ............ 100 
Protected datamember ............. 101 
TComboBox class...............00. 102 
Public constructors..............0.. 102 
Publicdatamember ............... 102 
Public member functions ............ 102 
Protected member functions .......... 106 
TComboBoxData class.............. 106 
Public constructor and destructor ....... 106 
Public member functions ............ 107 
Protected datamembers............. 108 
TCommandEnabler class ............ 108 
Public constructor ................ 111 
Type definitions. . 2... 6. eee ee es 111 
Public data members................ 111 
Public member functions ............ 111 
Protected datamembers............. 112 
TCommonDialog class............... 112 
Publicconstructor ................ 113 
Public member functions ............ 113 
Protected datamember ............. 113 
Protected member functions .......... 113 
Response table entries. ............. 114 
TCondFunc typedef ................ 114 
TCondMemFunc typedef... .......... 114 
TControlBar class...............00.% 115 
Publicconstructor ................ 115 
Public member function............. 115 
Protected member function. .......... 116 
TControlGadget class ............... 116 
Public constructor and destructor....... 116 
_ Protected datamember............. 116 


iii 


Protected member functions........... 116 
Response table entries............... 117 
TControl:class-< «¢ a2 .6% 44.4 EY Bw e 117 
Public constructors ...............0. 117 
Protected member functions. .......... 118 
Response table entries... ..........0.. 120) « 
TCreatedDC class................6. 120 
Public constructors and destructor ....... 120 
Protected constructor............... 120 
TCOPTsSOr Class: aids Foe ak wk oe es 121 
Public constructors and destructor ....... 121 
Public member function ............. 121 
Operatorss «2x iswatens oh esa wakan 122 
WDE ClASSe a5 hate on eee le eh ee 122 
Public constructor and destructor. ....... 122 
Public member functions............. 123 
Protected constructors............... 158 
Protected datamembers ............. 158 
Protected member functions. .......... 159 
TDecoratedFrame class.............. 159 
Type definitions ...............0.. 160 
Public constructor...............0. 160 
Public member functions............. 160 
Protected datamembers ............. 161 
Protected member functions........... 161 
Response table entries... ............ 162 
TDecoratedMDIFrame class........... 162 
Public constructor................. 162 
Protected member function ........... 162 
Response table entries. .............. 162 
TDesktopD© class) 3: % 2.428 eal ede oh 163 
Public constructor................. 163 
ADialOe Classis ig, 6 em cide a. Be BS Ae es 163 
Public datamembers ............... 164 
Public constructor and destructor........ 164 
Public member functions............. 164 
Protected member functions........... 167 
Response table entries... ............ 168 
TDialog class::TDialogAttr struct... ..... 168 
Publicdatamembers ............... 168 
TDib class. ..... eustecete, ee he a he th 169 
Type definitions: s.<. 4404 oe eta ere 169 
Public constructors and destructor ....... 169 
Public member functions............. 170 
Protected datamembers ............. 174 
Protected member functions........... 175 
TDIDDE Class: 3) se ae ok eS A ES 176 
Publicconstructors ..............06. 176 
TDocManager class.............0.. 176 
Public constructor and destructor........ 177 
Publicdatamembers ............... 177 


Public member functions 


ee eae ere 177 
Protected member functions .......... 181 Protected datamember.............. 213 
Response table entries.............. 182 Protected member functions. .......... 213 
~TDocument class. ............0004 182° TFileOpenDialog class.............8 213 
Public datamembers.......... eake howe 2 183 © Public constructor............6.... 214 
Type definition .................. 183 Public member function ............. 214 
Public constructor and destructor ....... 184 TFileSaveDialog class..............48 214 
Public member functions ............ 184 Public constructor... ........00004 214 
Protected datamembers............. 189 Public member function ............. 914 

Protected member functions .......... 189 TFilterValidator class............0.. 215: 

TDocument::List class... ........... 189 Public constructor............000- .215 

Public constructor and destructor. grate Bed aes 189 Public member functions. ............ 215. 
_. Publicmember functions ............ 190 Protected datamembers ............. 215 
-TEdgeConstraint struct ...........08 190 TFindDialogclass................. 216 
Public member functions ............ 190 Public constructor..............00. 216 
TEdgeOrSizeConstraint struct ......... 191 Protected member functions. ......... .216 
Public member functions ............ 192 TFindReplaceDialog class............ 216 
TE GIt ClaS6 ns: S.'-ar 6 ahs, Pa RON bw eed 192 Public constructor................. 216 
Public constructors................ 193 Public member functions. ............ 217 
Public member functions ............ 193 Protected datamembers ............. 217 

Protected datamember ............. 198 Protected member functions. .......... 217 | 

Protected member functions .......... 198 Response table entries... ..... al et Rtee Bse 218 
Response table entries. ............. 201 TFindReplaceDialog::TData class........ 218 
TE CitPile Class: <cig a: seater do BR 201 — Public constructor and destructor........ 218 
Public constructors and destructor GaP ina es fe . 201 Publicdatamembers ............... 218 
Public datamembers............. . . 202 TFloatingFrame class... ........... 919 
_ Public member functions ............. 202 Public constructor. ............000- 220 
Protected member functions .......... 203 Public member functions. ............ 220 
__ Response tableentries.............. 204 Protected member functions. .......... 220 
TEditSearch class 4.4.4 4:0 4.560 Ga & eo 204 Response table entries............... 221 
Public constructor .:.............. 204 TRontclass......... ce eee eee eee 2?1 
Public data members... .. . Site Gr baa 204 Public constructors .............-.. 221 
Public member functions ............ 205. ~——-~Public member functions. ............ 222 
Response table entries. ............. 206 TFrameWindow CIAGS «S28 on oe oe eg 929 
TEditView class...... ee ee 206 Public constructors and destructor bes gt 222 
Public constructor and destructor....... 206 Publicdatamembers ............... 923 
Public member functions ............ 206 Public member functions............. 223 
Protected datamember ............. 207 Protected datamembers ............. 225 
Protected member functions .......... 207 Protected constructor. ...........004 226 
Response table entries. ............. 208 Protected member functions. .......... 226 
TEqualOperator typedef........... . . 208 Response table entries... ........... 228 
TEventHandler class... . . 2s Bice say es OG 209 oo CASS see ce ete eS ete 228 

Public member functions ............ 209 Public constructors and destructor ....... 229 
Protected member function. .......... 209 Publicdatamembers ............... 229 
TEventHandler::TEventInfo class ....... 209 Public enums and structs............. 229 
Publicconstructor ..............6. 209 © Public member functions. ............ 230 
Publicdatamembers............... 210 Protected datamembers ............. 232 
TEventStatusenum................ 710 Protected member functions.......... :233 
TFileDocument class............000. 210 TGadgetWindowFontclass........... 234 
Public constructor and destructor....... 211 Public constructor... 1.2... 0.020008. 235 
Type eenmalions arty tnd ne, at Gana te Da eed TGadgetWindow class.............. 236 


iv 


Public member functions 


Public constructor and destructor ....... 236 
Type definitions... ...4% 44546086444 236 
Public member functions ........... 236 
Protected datamembers............. 239 
Protected member functions .......... 241 
Response table entries.............. 243 
TGaiee Classy. 2.4) a: Sscasana aa 8 bo eed oe . 243 
Publicconstructor ................ 243 
Public member functions ............ 243 
Protected datamembers............. 244 
Protected member functions .......... 245 
Response table entries.............. 245 
TGdiObject class ..............0.. 245 
Public destructor................. 246 
Type definitions... ............0.. 246 
Public member functions ............ 246 
Protected datamembers............. 248 
Protected member functions .......... 248 
Protected constructors.............. 248 
MaCtOS 4.7 Ae oe Sai le ee ee ew aS oe 248 
TGdiObject::TXGdi class... .......... 250 
Publicconstructor ................ 250 
Public member functions ............ 250 
TGroupBox class ..............0004 250 
Publicdatamembers............... 251 
Public constructors..............0.. 251 
Public member functions ............ 251 
THatch8x8Brush class .............. 252 
Public datamembers............... 252 
Public constructors...............0.4 253 
Public member functions ............ 253 
MAC CASS! ws -%, aos et ee, teak ow ee ws ak te, Bs 253 
Publicconstructor ................ 254 
WICOM ClaSS ine. ad Weel eles PS eee .. 204 
Public constructors and destructor....... 254 
Public member functions ............ 255 
TInputDialog class... ............. 20 
Publicdatamembers............... 255 
Publicconstructor ..............0.. 255 
Public member function. ............ 256 
Protected member function. .......... 256 
TInStream class ............20-e000., 256 
Public constructor ............ o an€ 4°20 
TLayoutConstraint struct. ........... 256 
Public datamembers............... 257 
TLayoutMetrics class............ cic 8. OO 
Public datamembers.......... deteeesn 2 259 
Public constructor ................ 259 
TLayoutWindow class. ............. 261 
BXOMIPICSs heise stk trae wee BARS SS 261 


Public member functions............. 263 


Protected datamember.............. 264. 
Protected member functions........... 264 
Response table entries. .............. 264 
TLIStBoxcclass’.oosece- dt 34 ek Bow bind Oe HS 264. 
Public constructors ................ 265 
Public member functions............. 265 
Protected member function ........... 270 
TListBoxData struct................ 270 
Publicdatamembers ............... 270 
Public constructor and destructor. ....... 271 
Public member functions............. 271 
TListView class ...............000. 272 
Public constructor and destructor. ....... 272 
Public datamember........ MS coctge Bs Bokeh 272 
Public member functions............. 273 
Protected datamembers ............. 273 
Protected member functions........... 274 
Response table entries... ............ 276 
TLocaleString struct. ............... 276 
Public member functions............. 277 
TLookupValidator class ............. 278 
Public constructor...............6. 278 
Public member functions............. 278 
TMDIChild class ...............0.. 279 
Public constructors and destructor ....... 279 
Public member functions............. 279 
Protected member functions........... 280 
Response table entries... ............ 281 
~TMbDi!IClient class ................. 281 
Public constructor and destructor........ 281 
Publicdatamember................ 281 
Public member functions............. 281 
Protected member functions........... 283 
Response table entries... ............ 284 
TMDIFrame class............. .... 284 
Public constructors ..............00. 285 
Public member functions............ .285 
Protected member functions........... 286 
Response table entries. .............. 286 
TMeasurementUnitsenum........... 286 
TMemoryD€ class: \s.5. si 5 eh fh. oe ae eae 287 
Public constructors ..............0. 287 
Public member functions............. 287 
Protected datamember.............. 287 
Mien ClaSS 3... ya Ah tsa ES, Ey ee 288 
Public constructors and destructor....... 288 
Public member functions............. 288 
Protected datamembers ............. 292 
Protected member functions. .......... 292 
TMenuDescr class..............0008% 293 


Public constructors and destructor....... 7 


Protected member functions 


295 
Type definitions... 0... 0.4. e ea aiee 296 
_ Publicmember functions ............ 296 
- Protected datamembers............. 297 
Protected member functions .......... 298 
TMenultemEnabler class ............ 298 
Publicconstructor ...............0. 298 
Protected datamember ............. 298 
~Public member functions............. 299 
TMessageBar class ..............5. 299 
-Publicconstructor ................ 299 
Public member functions ............. 299 
Protected datamembers............. 300 
Protected member functions .......... 300 
TMetabileioG Class +o: tw: <5. adeeuseae Aes 300 TOpenSaveDialog::TData struct ........ 344 
Public constructor and destructor ....... 301 Public constructors and destructor ....... 344. 
Public member function. ............ 301 Datamembers........ 2 ere eee 345 
TMetaFilePict class.............0-. 301 Public member functions... .......... 346 
- Public constructors and destructor....... 301 TOutStreamclass................. 346 
Public member functions ............ 302 Public constructor...............0. 346 
Protected datamembers............. 303. TPaintDC class..... eee fei eee ee 347 
TModule class................06. 303 Public constructor and destructor........ 347 
Public constructors and destructor. ...:. . . 303 Publicdatamember................ 347 
Public datamembers............... 304 Protected datamember.............. 347 
Public member functions ............ 304 TPaletteclass......... 0.000.000 347 
Protected datamembers............. 309 Public constructors ............-e.e.4. 347 
TModule::TXInvalidModule class. ....:. 310 Public member functions. ............ 348 
Public constructor ..............0.. 310 Protected member functions. .......... 350 
_ Publicmember functions ............ 310 TPaletteEntry class ................ 350 
TOleClientDC class................ 310 Publicconstructors ................ 351 
Public constructor .............044 311 TPenclass....... Cle Bode teoe & dace betes 351 
TOleDocument class................ 311 Public constructors ............. 351 
Public constructor and destructor ....... 311 Public member functions............. 352 
Public member functions ............ 312 TPicResultenum ................. 353 
TOleFactoryBase<> class ............ 314. TPlacementenum................. 353 
Public member functions ............ 315 TPopupMenuclass.............05. 353 
Template arguments..............-. 315 Publicconstructors ................ 353 
TOlePrame class. 9.4. te SSeS eRe Sx 316 Public member functions. ...:........ 353 
Public constructor and destructor....... 317 TPreviewPage class... ........0000. 354 
Public member functions ............ 317 Public constructor. .............0... 354. 
Protected member functions .......... 317 Public member functions. ............ 355 
Protected datamembers............- 320 — Protected datamembers ............. 355 
Response table entries... ........... 321 Protected member functions........... 355 
TOleMDIFrame class............... 321 Response table entries........... ... 356 
Public constructor and destructor ....... 322 =TPrintDC class........ Soe de ke Bch iy oe ask 2356 
Protected member functions .......... 322 Public constructors ............005. 356 
Response table entries... ........... 323 Public member functions............. 356 
TONG VIEW Class: 6 o> «oad sett ay Wor ch Ot eos o-e 323 Protected datamember.............. 363 
Public constructor and destructor'....... 323 TPrintDialog::TData struct............ 364 
_Public member functions ............ 324. Public datamembers ...........<:.. 364. 
OSE RR ah eee dt 324 Public member functions............ .366. 


Response table entries............. 326 


TOleWindow class ...........2...0.6. 326 
Public constructor and destructor. ....... O27 
Public member functions... .......... 327 
Protected datamembers ............ 329 
Protected member functions........... 330 
Response table entries............... 341 

TOpenSaveDialog class ............. 342 
Public constructor .................0. 342 
Public member functions. ............ 342 
Protected datamembers ............. 343 
Protected constructor .............46. 343 
Protected member functions. .......... 343 


Response table entries. .............. 344 


Vi 


TPrintDialog class... ...........0.. 367 
Public constructor ................ 368 
Public member functions ............ 368 
Protected datamembers............. 368 
Protected member functions .......... 369 
Response table entries.............. 369 

TPrinter class ..................4. 369 
Public constructor and destructor ....... 369 
Public member functions ............ 369 
Protected datamembers............. 370 
Protected member functions .......... 371 

TPrinter::TXPrinter class. ............ 372 
Public constructors................ 372 

TPrinterAbortDlg class... ........... 372 
Publicconstructor ..............08. 372 
Protected member functions .......... 372 

TPrintout class... 2d -0 4% eel oe we RS 373 
Public constructor and destructor ....... 373 
Public member functions ............ 373 
TV pe GenninONns sis... <6 OS el ie ee 374 
Protected datamembers............. 375 

TPrintPreviewDC class ............. 375 
Public constructor and destructor ....... 376 
Public member functions ............ 376 
Protected datamembers............. 379 
Protected member functions .......... 379 

TProfile class..................-. 379 
Public constructor and destructor ....... 379 
Public member functions ............ 380 

TPXPictureValidator class............ 380 
Publicconstructor ...............0. 380 
Public member functions ............ 380 
Protected datamember ............. 382 

TRadioButton class..............0. 382 
Public constructors. ..............0. 382 
Protected member functions .......... 383 
Response table entries. ............. 383 

TRangeValidator class.............. 383 
Public constructor ................ 383 
Public member functions ............ 383 
Protected datamembers............. 384 — 

TREPIONClaSS 2502.8 St ee fee a aise % 384 
Type dehnitiOnss ioe Cae wee + wes 384. 
Public constructors................ 384 
Public member functions ............ 385 

TRelationshipenum ............... 387 

TReplaceDialog class............... 387 

- Publicconstructor ................ 388 
Protected member function. .......... 388 

TResponseTableEntry class........... 388 

Public datamembers............... 388 


Vil 


Type definitions 


Sac tc? Be eas rte Sa tesa 389 

TRepOuad elasss. & 2.4 eh -6G-F are eh ue Sty oth 389 
Public constructors ................ 389 
TReb Inpleiclasso.2 4.4.9 4 8 lh oe 390 
Public constructors ................ 390 
TScreenDC class...............00. 390 
' Publicconstructor..............0-. 390 
TSerouBbar classe. 2-5 écca of oe okie Se 391 
Publicdatamembers ............... 391 
Public constructors ................ 391 
Public member functions... ........0... 392 
Protected member functions. .......... 394. 
Response table entries............... 394. 
TScrollBarData struct. .............. 394 
Public datamembers ............... 394 
TESCROME?R. CLASS: axiy-5. 4 ao. x Salah sac Bc Bewss 395 
Public datamembers ............... 395 
Public constructor and destructor. ....... 396 
Public member functions............. 396 
TSeparatorGadget class ............. 398 
Public member function ............. 399 
TSliderclass ............20.00000. 399 
Public constructor and destructor........ 400 
Public member functions............. 400 
Protected member functions. .......... 401 
Protected datamembers ............. 404. 
Response table entries............... 405 
TIS Ger ClaSScce sar Se we bw Sk ee KS 405 
Public constructors ..............4. 406 
Protected member functions. .......... 406 
TV Slider class ofc ee ok dea ck OEE EAA 407 
Public constructor...............0. 407 
Protected member functions. .......... 407 
TSortedStringArray class ............ 408 
Public constructor................6. 408 
Type definitions .................. 408 
Public member functions............. 408 
TStAUC CASS) <i wo Se oS ee SI ee 410 
Public datamembers ............... 410 
Public constructors ................ 411 
Public member functions. ............ Alt 
Protected member functions. .......... 412 
Response table entries............... 412 
Status ClASS  a..é: e405. ee te by hewd ce be we 412 
Public constructor...............0. 412 
Public datamembers ............3.. 412 
TStatusBar class...............04. 413 
Type definitions ................6. 413 
Public constructor. ..............008.4 414 
Public member functions. ............ 414 
Protected datamembers ............. 415 


Protected member functions 


Response table entries... .........08. 451 
WIC W°ClaSSe &: gee a a oh et gts A 451 
Publicdatamembers ............... 452 
Public constructor and destructor........ 452 
Public member functions. ............ 452 
Protected datamember.............. 454. 
Protected member functions. .......... 454 
TWidthHeightenum............... 454 
TWindow class. ..........0...0.00. 454 
Publicdatamembers ............... 455 
Public constructors and destructor ....... 456 
Public member functions. ............ 457 
Protected datamembers ............. 489 
Protected constructor............... 490 
Protected member functions. .......... 49] 
Response table entries... ............ 494 
TWindowAttr struct .........0...008 494. 
Publicdatamembers ............... 495 
-TWindowFlagenum ............-.-. 496 
. TWindowDC class ........0.....002. 497 
Public constructor and destructor Sav sces, oe hee & 497 
Protected constructor ............... 497 
| Protected data Member essa 9 2.06242 a more 497 
TWindowView class .............-- 498 
Public constructor and destructor... ..... 498 
Public member functions. ............ 498 
Response table entries............... 499 
TWindow::TXWindow class. ........... 499 
Public constructors..........0....... 499 - 
Publicdatamembers ............... 499 
Public member functions. ............ 499 
TXCompatibility class .............. 500 
Public constructors: ¢ 4 6 4 eke & Base & 500 
Public member functions. ............ 500 
TMenu::TXMenu class.............. 501 
| Public constructors .............00. 501 
Public member functions. ..........0. 501 
TXOutOfMemory class.............. 501 
Public constructors ................ 501 
Public member functions ree oe ae ee 501 
TXOwl class ....... 25, Sitios ONE Ac Fo, ge Bs 502. 
Public constructors and destructor ....... 503 
Publicdatamember................ 503 
Public member functions. ............ 504. 
VNXxxx view notification constants. ...... 504 


Protected member functions: 


Chapter 3 


TStorageDocument class............. 416 
Type dennitionss 4.4 32258 Sa estes wig OS 416 
‘Public constructor and destructor....... 417 
Public member functions ............ 417 

_ Protected datamembers............. 420 

: PStreanny Class: 14%. a aca OO eS Gd 420 
Public destructor ...............0.. 420 
Public member functions ............ 420 
Protected datamembers............. 421, 
Protected constructor............... 421: 
TStringLookupValidator class ......... 421 
Public constructor and destructor ....... 421 
Public member functions ............ 421 
Protected datamember ............. 422 

— TSystemMenu class................ 422 
Public constructor ................ 422 
WlextGad get class): v4 5.0.4. « ae a4 Mee hom 422 
Public constructor and AeeRiC toe be Been aoo 423 
Public member functions ............ 423 
Protected datamembers............. 423 
Protected member functions .......... 423. 
Type GenminOns ss 2.2 a:6-4.- etew.t Se se 2 424 
TTinyCaption class................ 424 
Protected datamembers............. 425 
Protected constructor and destructor ..... 426 
Protected member functions .......... 426 
Response table entries... ........... 430 
TPIOOLBOXCClASS = andes B 00s oe Ae eGR RS 430 
PUBNCCONSHUCO! «ex. 45 ks aS a eS 43] 
Public member functions ............ 431 
Protected datamembers.............. 43] 
Protected member function. .......... 432 
TTransferDirection STUY g550:58:19 ie BS 8 ls 432 
TUlIHandle class........ ly 2c ermugaicn cee 432 
Type definitions... ... Pe ee ee 433 
Publicconstructor .............08.. 435 
Public member functions ............ 435 
TValidator class................0.. 436 
Public constructor and destructor ....... 437 
Public member functions ............ 437 
Protected data members. ............. 439 
Type CenMilONS 5 3.2 Bs 5 RS 439° 

~ TValidator: ‘TXValidator class.......... 440 
PUbIGGONSHUOD 5.4 y ease ak Ae 440 
TVbxControl class .....0........0.. 440 
Public constructors and destructor Bee th ee 44] 
Publicmember functions ............ 442 
Protected member functions .......... 446 
Response table entries... ........... 446 
TVbxEventHandler class............. 447. 


— vill 


ae lat event handlers 505 


Chapter 4 
ObjectWindows dispatch functions 513 


List of ObjectWindows dispatch functions . . 514 
i LPARAM _Dispatch .............. 514 
LA WU. Dispatch 220.55 oh wk GA 514 
i_WPARAM_Dispatch.............. 515 
132 Dispatches 2d a0 250 aie Ee eo eid ae 515 
132_LPARAM_Dispatch............. 515 
132_WPARAM_LPARAM Dispatch. ..... 515 
132_MenuChar_Dispatch............ 515 
192 3U. DIS PatChia 2m xc Athenee we Boas 515 
WW EDISPAICNy 3.923 2k hae e e Se 515 
U_LPARAM_Dispatch.............. 516 
UPOUN E sDispatehi, se xa: acie a a daea Hes 516 
U_POINTER_Dispatch ............. 516 
NPIS AUC it ae ok 2 aoa andi yh tha, ete ee 516 
UU UU Dispatch: 5.26 «a cee ce phe 516 
U_WPARAM_LPARAM_Dispatch ...... 516 
v_Activate_Dispatch............... 516 
VeDDISPAICs Sa ne Se BS Ka RS Cae 516 
v_LPARAM_Dispatch.............. 517 
v_MdiActivate_Dispatch ............ 517 
v_ParentNotify_Dispatch............ 517 
Vv POINT. Dispatch. 2.4. fue KES Fe ah tes 517 
v_POINTER_Dispatch.............. 517 
VU Dispatches 225% 2:4. ss Ob aver AS ee ai 517 
v_U_POINT_Dispatch.............. 518 
YU Dispatch 2.2 42 & 4.6 weal anda Boa hase 518 
VU JU OU! Dispatch: y.0 5. ite a ree o 518 
VU UW Dispatens. sess oo ee ee ory 518 
V_WPARAM _ Dispatch ............. 518 
v_WPARAM_LPARAM Dispatch... .... 518 

Part IL 

ObjectComponents reference 519 

Chapter 5 

Overview of ObjectComponents 521 

ObjectComponents libraries... ........ 521 

ObjectComponents header files ........ 522 

General OLE classes, macros, and type 

GeHNIHONS 6 ee ie hee es ees eee 522 

Global utility functions. ............. 523 

ObjectComponents exception classes... .. 523 

Automation classes... ..........004 523 

Automation enumerated types and type 

definitions ........ aaeeerr sa 524 
Automation datatypes. ............. 524 
Declarations and definitions of automation 

data: ty PeSi rr é.5: 24.998 ke KORA ERS 524. 


Automation declaration macros ........ 525 
Automation definition macros ......... 526 
Automation hook macros ............ 527 
Automation proxy macros............ 528 
Registration keys ...............0.. 529 
Linking and embedding classes ........ 530 
Linking and embeddingenums ........ 532 
Linking and embedding messages. ...... SoZ 
Linking and embedding structs......... 532 
ocrxxxx constants... ..........000.. 533 
Chapter 6 
ObjectComponents library 
reference 535 
NO TGANSS MIA CIO! ingaes ae aver car eds oe 535 
WING IMA CTOs ioe, ie hca Aas eae Boa ok a 935 
OE POOOG INA CIOS»: a6 Sane de es 535 
aspectall registration key............. 536 
aspectcontent registration key.......... 536 
aspectdocprint registration key......... 537 
aspecticon registration key......:..... 937 
aspectthumbnail registration key........ DoT 
AUTOARGS macros ............... 538 
AUTOCALL_xxxx macros. ........... 538 
~AUTOCLASS macro .............. 539 
AUTODATA macros... .........0... 539 
AutoDataTypeenum............... 540 
AUTODETACH macro. ............. 540 
AUTOENUM macros .............. 541 
AUTOFLAG macro................ 541 
AUTOFUNC macros............... 542 
AUTOINVOKE macro.............. 543 
AUTOITERATOR macros............ 543 
AUTONAMES macros. ............. 544 
AUTONOHOOK macro. ............ 544 
AUTOPROP macros ............... 545 
AUTORECORD macro. ............. 545 
AUTOREPORT macro.............. 545 
_AutoSymFlagenum .............5. 546 
AMUTOSTAT MAaCtOS sc sus) joe ace WS Sed 546 
AUTOTHIS macro ................ 547 
AUTOUNDO macro............... 548 
AUTOVALIDATE macro. ............ 548 
clsid registration key ......:........ 548 
cmdline registration key............. 549 
debugclsid registration key ........... 549 


-debugdesc registration |) ene eae bee 549 


debugger registration key. ...... ba, ss OOO 
debugprogid registration key.......... 550 
DECLARE AUTOCLASS macro. ....... 551 
DECLARE COMBASESn macros....... 551 
DEFINE_AUTOAGGREGATE macro. ... . 552 
_ DEFINE_AUTOCLASS macro......... 552 
~ DEFINE _COMBASESn macros ........ 553 
description registration key........... 553 
directory registration key ............ 554 
docfilter registration key............. 554: 
_docflags registration key............. 554 
DynamicCast function. .... Qian d 555 
END_AUTOAGGREGATE macro. ...... 555 
END_AUTOCLASS macro........... 555 
EXPOSE_APPLICATION macro. ....... 556 
EXPOSE,_DELEGATE macro.......... 556 
EXPOSE_INHERIT macro. ... . heart TOOT 
EXPOSE_ITERATOR macro ........ aor 
EXPOSE_METHOD macros ..... its, Sees 558 
EXPOSE_PROPxxxx macros .......... 559 
~ EXPOSE _QUIT macro............ .. 560 
extension registration key......... ... 560 
filefmt registration key......... ee 561 - 
formatn registration key............. 561 
handler registration key............. 561 
_ helpdir registration key ............. 562 
HR_xxxx return constants. ......... .. 562 
iconindex registration key............ 563 
insertable registration key. ........... 563 
language registration key ............ 564: 
menuname registration key. .... ig BeBe Seo OE 
MostDerived function.............. 564 
ObjectPtr typedef... .........2005- 564 
OC_APPxxxx messages. ............ 565 
OC_VIEWxxxx messages. ........... 565 
Ocrxxxx aspect constants............. 566 
ocrxxxx Clipboard constants .......... 567 
ocrxxxx direction constants........... 568 
ocrxxxx limit constants.............. 568 
Ocrxxxx medium constants ......... .. 068 
ocrxxxx object status constants......... 569 
Ocrxxxx usage constants. ............ 570 
ocrxxxx verb attributes constants... .... . 570 
ocrxxxx verb menu flags. ............ 570 
OPTIONAL ARG macro....... Mnddhis 571 


path registration key............... 571 


permid registration key Sin She i Se he ics, Ole 


permname registration key ......... uae Os 2 
progid registration key........ oe oe 572 
REQUIRED_ARG macro. ... . de din tame Bacts eck 573 
-TAutoBase class.............. tae « OO 
Public destructor.................4. 573 
TAutoBool struct ..............00. 574, 
Publicdatamember...... ee wae en a 574, 
TAutoCommand class...... we the te ah ancdestey OTD 
Public constructor and destructor. ....... 574. 
Type Gemmitions: 1-8, a4 eae ale ox Swe 574. 
Public member functions. ............ 575 
Protected datamembers ............. 577 
TAutoCurrency struct .............. 577 
Publicdatamember................ 577 
TAutoDate struct ....... tints 1h Be Teach Meee 578 
Publicdatamembers ............... 578 
Public constructors .............0. 578 | 
Public member function ............. 578 
TAutoDouble struct... .... a ae Sete aise 578 
Public datamember.............. —, 578 
TAutoEnumerator<> class............ 579 
Public constructors and destructor ....... 579 
Public member functions. .... A Woy We eee OD 
TAutoFloat struct.......... BY pate ah 580 
-Publicdatamember................ 580 
TAutolterator class ................ 581 
Public member functions............. 581 
Protected constructors............... 583 
Protected datamember......... los. 4 4acts 583 
TAUtOLOng SIUCE sy 3 oii t.ar som dob oa 583 
Public datamember.......... BAe eee OS 
TAutoObject <> class... .........0.. 584 
Public constructors ................ 584. 
Public member functions... .......... 584. 
Protected datamember.............. 585 
TAutoObjectByVal<> class... .. ee ee 585 
Public datamember................ 585 
Public constructors ................ 586 
TAutoObjectDelete <> class........... 586 
~ Publicconstructors ................ 586. 
- Public member functions. ............ 586 
TAutoProxy class. ............. Se GOT; 
Public destructor..............0... 587 
Public member functions............. 587 
Protected constructor............... 589 
Protected member function ........... 589 
TAutoShort struct............ pated cess, 590 | 
_ Publicdatamember................ 590 


TAutoStack class...............00. 590 


Public constructor and destructor ....... 590 Public member functions............. 623 


Public member function. ............ 591 Public datamembers ............... 623 
Public datamembers............... 591 TOcNameList class ..............e8048 624 
CONStANE 6 4:96 so) Betis we ee Beh 592 Public constructor and destructor........ 624 
TAutoString struct ................ 592 Public member functions............. 625 
Public constructors and destructor. ...... 592. TOcPartclass............00050000- 626 
Public member functions ............ 593 Public constructors ..............04 626 
Publicdatamember ............... 593 Public member functions............. 626 
TAUtO Ty pe Struct «6.20544 2 ed ae d 594 Protected destructor................ 631 | 

Public member function............. 594 TOcPartCollectionclass ............. 631 
TAutoValclass............ 008. eee 5904 Public constructor and destructor........ 632 
Public member functions ............ 595 Public member functions............. 632 
TAutoVoid struct................0.4 598  TOcPartCollectionlterclass........... 633 
Publicdatamember............... 599 Public constructor...............6. 633 
TComponentFactory type definition ..... Boo): Public member functions............. 633 
TLocaleId type definition ...... Oe an at ee 599 TOcPartNameenum............... 634 
TOCA piClass 64's uh os Gd eee aoe eA 600 TOcRegistrarclass................. 634 
Type definitions... ............0.. 600 Public constructor and destructor........ 635 
Public member functions ............ 601 Public member functions. ............ 635 
Protected constructor and destructor ..... 606 Protected member functions........... 636 
Protected member functions .......... 606 TOcRemView class................ 637 
TOc AppMode enum............ee. 607 Public constructor................. 637 
TOcAspectenum...........00000- 608 Public member functions............. 638 
TOcDialogHelpenum.............. 608  TOcSaveLoad struct ............... 639 
TOcDocument class ............... 609 Public datamembers ........-..-+-, 640 
Public constructors and destructor....... 610 TOcScaleFactor class... 0.6... ..004. 640 
Public member functions ............ 610 ees Sasa ere ee ee oS 

ublicdatamembers ............... 
eet neh oceans a es et ne dos ine Public member functions............. 641 
TOcDropActionenum............0. 613 TOcScrollDirenum..............0. 642 
TOcFormatList class ............... 614 TOcToolbarinfo struct... . 2... eee ee. 642 
Publiesonseicror and destructor << cc 2< 614 Publicdatamembers ........ eS Sey 643 
Public member functions ............ 614 stay saa ee ne a 

| ublicconstructor...............0.. 
RNa crtcscesrs ts 5 Publediamenbas © 000000000000 e 
Public member functions ............ 616 eval sued ‘ Se i ee oe eee ve 

TOcFormatName class.............. 616 BE NON O pS oe ogi Araki My A Oa 
Public constructors and destructor. ...... 617 Public member functions... ........-. 646 
Pabliemenibertinchone concn, ep deeciek te 617 Protected destructor. . ee 649 
TOcisiGirenan 618 Protected member functions........... 649 
Pea eee ee, eee ge ee enyeg ope eee Protected datamembers ............. 650 
ete class asses ee TOcViewPaint struct..............0. 651 
Shs ae an pica OE ge Pie eS) TS ae Publicdatamembers ............... 651 
Peblic mice ConeGOne ¢ ito wet-cs cote 620 TOleAllocator ClASS so. 4S hk, Bie Be hee 652 
TOcinitWhereenum........... 690 Public constructors and destructor ....... 652 
; Public member functions............. 653 
TOcInvalidateenum.............-. 621 Publicdatamember................ 653 
TOcMenuDescr struct... . 2... 2+. 621 TRegistrarclass.........000 00000. 653 
Public datamembers............... 622 Public:consticior and destructolis sc estan 654 
TOcModule class gba aes’ & Pl Se eee. BS. et tek we He 622 Public member functions sa Net hs. he So me, de /us Gi oh te, sen 654 
Public constructor and destructor....... 623 Protected datamember.............. 657 


_ Protected constructor.............. 
TUnknown class .:............004 
Public member functions ........... 
~ Protected constructor and destructor 
Protected member functions 
Protected datamember ............ 
TX Ato Class. 4 aiid dbase ee oa eh 
Public constructor ............... 
Public data member 
Type Ceninion, 4%, 6.2 a acai csun See ee Oe 
TXObjComp class................. 
Public constructor 
Public member function. ........... 
_ Type definition... ............... 
TXOle Classis ees Beata, CSRS 
Public constructors and destructor...... 
Public member functions 
Public data member 
TXRegistry class... ... er ere ee ee 
Public constructors..............6. 
Public member functions 
typehelp registration key 
usage registration key 
verbn registration keys.......... cee 
- verbnopt registration keys............ 
version registration key 


ee e 8 © © ee #8 ee @ 


ee ee e e © ee e@ © e@ © @ 


oo e«© ee e e @ @ @ @ ‘© @ ee e# @ 


ee e e ee @ e© @© @ @ #® ee oe @ 


_ WM_OCEVENT message... ...... bg, ee 


Part I 
ObjectSupport reference 


Chapter 7 
Overview of ObjectSupport 


Chapter 8 © 

ObjectSupport library reference 
Registration macros. ............... 
BEGIN_REGISTRATION macro........ 
END_REGISTRATION macro ......... 
REGDATA macro... ........-0204. 
REGIE M Maer sce: Se ee oko Bad ode ae 
REGFORMAT macro............... 
REGSTATUS macro. ...... Lutte eon ae 
REGVERBOPT macro .............. 
REGICON macro..........0.000004 


REGDOCFLAGS macro. ........ eee 


REGISTRATION_FORMAT_BUFFER 


* e© ee e© © ee ee © 8 © © © e@© © © #© ee 8© © @ 8 © © 


TDocTemplate Glass 5". soncki tears tees 


679 
Public member functions. .......... Seg O79 
Protected constructor and destructor... . . .683 
TDocTemplateT<D,V> class........... 683 
_ Public constructors .............00.4. 684 
| Public member functions........... . 684 
TDropinto class: cmes.8 + a a.go- dew o- 685 
Publicconstructor............0000- 685 
Public member functions............. 685 
TLangld typedef...............00. 686 
TPointclass: <4. 4-2 245 26 Sones R484 3 os 686 
Public constructors-............... .687 
Public member functions... ........... 687 
TPointer<> class. .... eas os loki og ate -. 689 
Public constructors ...... teapots sd tale ds AE 689 
Public member functions............. 689 
TProcInstance class................ 690 
Public constructor and destructor. ....... 690 
Public member function ee ree + haa ahh aes 690 
"PREC ClASS:.< a 2S es OS ee hee 690 
Public constructors ..... ee re re 691 
Public member functions. ...... rere 691 
TResId class ............ 008 eee 696 
Public constructors .............000. 697 
Public member functions. ............ 697 
Friend functions ..............008. 697 
~ HSIZE CASS <i... Soe 8 oe nd, KS sw 697 
Public constructors .............200. 698 
Public member functions............. 698 
TXBase Class © wack. ka & tw Marke oa aa 3 699 
Public constructors and destructor ....... 700 
Publicdatamember................ 700 
Public member functions............ 700 
Appendix A 
Windows API encapsulated | 
functions 701 
Appendix B | 
Windows API structs 707 
ABC SHUG < do 6k eS eR oe ee 707 
BLIMAP Struict:.2: 30 cha Se Gawd RES a 707 
BITMAPCOREHEADER struct. ...... .. 708 
BITMAPCOREINPFO struct ........... 709 
BITMAPINFO Struct \s: a.0:5 2:8 See eo eles 710 
BITMAPINFOHEADER struct......... 711 
COLORREF typedef ........ sic gees cetera 713 
COMPAREITEMSTRUCT struct. ee ee 713 
714. 


DELETEITEMSTRUCT struct Great eis El a gos 


DEVMODE SIMIC m2 Soe bee 31475 4G eg ee 714 METARECORD struct.............. 729 


DRAWITEMSTRUCT struct .......... 718 MEASUREITEMSTRUCT struct........ 729 
FINDREPLACE struct.............. JQ). NASGs SEUCE: 6 fs: Sosee ear & Si ack eo e R ee 730 
GLYPHMETRICS struct............. 722. OUTLINETEXTMETRIC struct......... 730 
HANDLETABLE struct ............. 722 RGBOUADstruct................. 733 
ICONINFO struct............2.005 722 KRGBTRIPLEstruct ................ 733 
KERNINGPAIR struct.............. 723. TEXTMETRIC struct............... 733 
LOGBRUSH struct................ 723 WNDCLASS struct................ 736 
LOGFONTF struct ..04.4 <6 4 44444545 724 PAINTSTRUCT struct .............. 737 
LOGPALETTE struct............... 727 PALETTEENTRY struct............. 738 
DOGPEN SEMCES sido Sac ¥ oa lh od eed Taf KXKEFORM SHUCt s é.6 oh88 62 SS ASS 738 
MDICREATESTRUCT struct. ......... 728 | 

Index 741 


Xill 


Tables 


1.1 . Summary of the ObjectSupport library 


HICSS 20ers Be SY ak a kon eae eee 16 


1.2 Summary of staticlibraries ...........16 
1.3. Summary of dynamic link libraries ...... 17 


1.4 ‘Target applications and compiler options. . . 17 
1.5 Summary of options for building an 
ObjectWindows static or dynamic library. . . 18 
1.6 Summary of options for using an 
ObjectWindows static or dynamic library. . . 19 
1.7, Compile options for COOWLCLASS macro . . 19 


1.8 Summary of header files............. 19 
1.9 Summary of resource files............ 23 
1.10 New ObjectWindows data types........ 24. 
2.1 Button flag constants............... 28 
2.2 Button message constants........ et LO 
2.3 Combo box message constants......... 28 
2.4 Command-based constants........... 29 
2.5 Command-based constants ........... 29 
2.6 Command-based constants ...... rea ee 30 
2.7. Command-based constants ........... 30 
2.8 Command message constants.......... 31 
2.9 Dialog control message constants ....... 33 
2.10 Edit message constants.............. 35 
2.11 TWindow attribute masks. ......... . 496 
3.1 Button notification messages ......... 505 
3.2 Child ID notification messages ....... . 505 
3.3. Combo box notification messages ...... 506 


3.4 Command messages.............. -.506 
3.5 Document manager messages......... 506 
3.6 Document view messages .......... 006 
3.7 Edit control notification messages. . . ... . .507 

3.8. List box notification messages......... 507 
3.9 ObjectComponents messages ......... 507 
3.10 Scroll bar notification messages ........ 508. 
3.11 Standard Windows messages ......... 509 
O12 VBX Messaces 6.6 o's Sa ee Oe ae ee G 912 
3.13 User-defined messages ............. 512 
7.1 Summary of the ObjectSupport library 

GHC A ies ais ten se, Sh oa SSS re Rise Ze 672 
A.1_ Encapsulated inline HWND functions se woe ZO2 
A.2. Encapsulated Window messages ....... 702 
A.3 Window coordinates and dimensions . . . .702 
AA Window properties ............... 703 
A.5 Window placement ............... 703 
A.6 Window relationships. ..... ee ee 703 
A.7 Window painting functions .......... 704 
A.8 Window scrolling functions .......... 704 
A.9 Child window ID functions .......... 705 
A.10 Menu and menu bar functions. ........ 705 
A.11 Clipboard functions ............ .. .705 
AL12 ‘Timer functions «5-4: ee a wa eh 705, 
A.13 Caret and cursor functions. ....... .. 706 
A.14 Hot key functions ...... te dedi 8, fe Stes 706 
A.15 Help and task functions. ............ 706 


Figures 


1.1 Base class with several derived classes ..... Zz 
1.2 ObjectWindows hierarchy. ............ 8 


1.3 ObjectWindows hierarchy. ............ 2 


5.1 Hierarchy of ObjectComponents connector 
classes. ..... Pee ee ees 531 


Introduction 


This Reference Guide can be used to help you perform the following tasks in 
ObjectWindows: 


e Look up the overall purpose for each class. 


e Learn the details about how to use a particular ObjectWindows class and its members 
and functions. 


e View the virtual and nonvirtual multiple inheritance relationships among 
ObjectWindows classes. 


e Learn which classes introduce or redefine functions. 

e Determine which ancestor of a class introduced a data member or member function. 
e Learn how data members and member functions are declared. 

e Create OLE2 applications easily by using ObjectComponents classes. 

¢ Use the ObjectSupport Library (OSL) to support mathematical and file operations. 

¢ Use event-handling functions to respond to messages. 


e Use dispatch functions to crack Windows messages. 


What's new in ObjectWindows 2.5 


ObjectWindows 2.5 provides several new features that make it easier for you to design 
applications that run faster, write code that’s easier to debug, and create programs that 
implement linking and embedding technology. ObjectWindows 2.5 provides the 
following enhancements over version 2.0: 


¢ Complete encapsulation of OLE2 using ObjectComponents including 
e Linking and embedding containers 
¢ Linking and embedding servers 
¢ Automation servers 
e Automation controllers 
¢ OLE clipboard operations 
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—@ OLE drag and drop operations 
° In-place editing 


° OLE user interface, including menu merging, Pop-up } menus for activated object 
verbs on the container’s Edit menu 4 


° Compound file storage 
¢ Registration 

© Localized strings for international a 
° Type libraries 


e New data type definitions. See Chapter 1 of this manual for a list of the new data type — | 
_ definitions. 


. Internal diagnostic classes for increased debugging eapabiices 


. ObjectSupport classes that include new classes as well as utility classes previously 
included in the ObjectWindows library. See Chapter 1 of this manual for a 
description of the new support classes. 


Contents of this manual 
This manual is divided into three parts and includes two appendixes. 
Part I, “ObjectWindows reference,” includes the following four reference chapters: 


Chapter 1, “Overview of ObjectWindows,” provides an overview of the 
ObjectWindows classes, libraries, and header files. It organizes the classes according 
to functional groups and explains the purpose of each class within that group. 


Chapter 2, “ObjectWindows library reference,” is an alphabetical listing of all the 
standard ObjectWindows classes, including explanations of their purpose, usage, 
and members. It also describes the nonobject elements such as structures, constants, 
variables, and macros that classes use. 


Chapter 3, “ObjectWindows event handlers,” lists the ObjectWindows functions 
and notification codes that crack Windows messages. | 


Chapter 4, “ObjectWindows dispatch functions,” lists all of the ObjectWindows 
functions that dispatch Windows messages. 


Part Il, “ObjectComponents reference.” The second second part of this manual 
describes all of the ObjectComponents classes, structures, constants, types, and macros. 
It includes the following chapters: 


Chapter 5, “Overview of ObjectComponents,” provides an overview of the 
ObjectComponents classes, libraries, and header files. It describes the classes 
according to their functional groups and explains their purpose within that group. 


Chapter 6, “ObjectComponents library reference,” is an alphabetical listing of all 
the standard ObjectComponents classes, including explanations of their purpose, 
usage, and members. It also describes the nonobject elements such as structures, 
constants, variables, and macros that classes use. | 
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Part II, “ObjectSupport reference.” The third part of this manual describes all of the 
ObjectSupport classes, structures, constants, types, and macros. It includes the following 
chapters: 


Chapter 7, “Overview of ObjectSupport,” provides an overview of the 
ObjectWindows classes, libraries, and header files. It organizes the classes into 
functional groups and explains the purpose of each class within that group. 


Chapter 8, “ObjectSupport library reference,” is an alphabetical listing of all the 
standard ObjectSupport classes, including explanations of their purpose, usage, and 
members. It also describes the nonobject elements such as structures, constants, 
variables, and macros that classes use. 


Appendix A, “Windows API encapsulated functions,” lists the ObjectWindows 
functions that encapsulate Windows API functions. 


Appendix B, “Windows API structs,” lists the Windows structures that 
ObjectWindows uses. 


Typefaces used in this manual 


Boldface 
Italics 
Monospace 
Key! 
Key1+ 


Key2 


Menu| 
Command 


Note 


Boldface type indicates language keywords (such as char, switch, and begin) and 
command-line options (such as —rn). 


Italic type indicates program variables and constants that appear in text. This typeface is 
also used to emphasize certain words, such as new terms. 


Monospace type represents text as it appears onscreen or in a program. It is also used for 
anything you must type literally (such as TD32 to start up the 32-bit Turbo Debugger). 


This typeface indicates a key on your keyboard. For example, "Press Esc to exit a menu. 


Key combinations produced by holding down one or more keys simultaneously are 
represented as Key1+Key2. For example, you can execute the Program Reset command by 
holding down the Ctrl key and pressing F2 (which is represented as Ctrl+F2). 


This command sequence represents a choice from the menu bar followed by a menu 
choice. For example, the command "File |Open" represents the Open command on the 
File menu. 


This icon indicates material you should take special notice of. 


Conventions used in this manual 


Cross-referenced entries to ObjectWindows functions include the class name, the COPE 


resolution operator, and the function name. For example, 


See also: TApplication::PumpWaitingMessages 


C++ data types that are keywords (such as int and long) are in lowercase bold. 
Predefined Windows types (such as HWND) are in capital letters; for example, 


bool TrackPopupMenu(uint flags, int x, int y, int rsvd, HWND wnd, TRect* rect=0); 


" 
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4 ObjectWindows Reference Guide — 


ObjectWindows reference | 


Part |, ObjectWindows reference 5 


6 ObjectWindows Reference Guide 


Overview of ObjectWindows 


This chapter provides an overview of the ObjectWindows classes, libraries, and header 
files. It describes the classes according to the functional groups represented on the 
ObjectWindows hierarchy diagram. 


Hierarchy diagram 


The ObjectWindows hierarchy diagram shows the classes that are described in this 
manual. The classes are grouped according to functional categories, and all related 
classes are in one shaded unit. A rectangle surrounds the name of the class. A class is 
enclosed in dashed lines if it is a parent class for a multiply-inherited class. For example, 
T ListBox is the parent class for TList View, which is derived from both TView and 
TListBox. Base classes are placed above inherited classes and are connected to inherited 
classes by straight lines. The triangle on the connecting lines indicates the type of 
inheritance association that exists between the classes. A filled-in triangle indicates 
virtual inheritance between the parent and its derived classes; an open triangle 
illustrates nonvirtual inheritance. 


Figure 1.1 Base class with several derived classes 


Base Class 


Derived Class Derived Class Derived Class 
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Figure 1.2 ObjectWindowshierarchy = ie ge 
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Using ObjectWindows classes 


The ObjectWindows hierarchy includes a forest oe classes that you can use, modify, or 
derive from in order to create your own application. This section describes these groups 
of classes and how you can use them to build your application. These classes, which are 
displayed on the Object Windows hierarchy chart, can be divided into the following 
groups. 


e Base classes — 


¢ Window management classes 
e Frame windows 
¢ Decorated windows 
* Common dialogs 
¢ Controls 
° Gadgets 
e Menus 


¢ Module and application management classes 
¢ Command enabling 
e Doc/view 
¢ Print and print/preview 


e Graphics classes 
¢ GDI objects 
e Device contexts 


e Validators 
e Exception handling classes 
e Support classes 


Base classes 


TEventHandler, TStreamableBase, and TGdiBase are important base classes. All 
ObjectWindows classes are derived from one or more of these classes. Classes that 
inherit from TEventHandler are able to respond to window messages. Classes that inherit 
from TStreamableBase support streaming, that is their objects can write to and read from 

_ streams. Almost all of the ObjectWindows classes are derived from TStreamableBase. You 
can use multiple inheritance to derive a class from both TEventHandler and 
TStreamableBase. Classes that inherit from TGDIBase, a private base class, support GDI 
drawing objects such as pens, brushes, fonts, and bitmaps. 


e TEventHandler sends messages to the appropriate message handler. 
e TStreamableBase provides support for C++ streaming and persistence. 
¢ TGdiBase is the root class for all derived GDI classes that support Windows’ GDI 
library. 
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Window management classes 


Derived from TEventHandler and TStreamableBase, TWindow is the parent class for all 
window classes. It represents the functionality common to all windows, whether they 
are dialog boxes, controls, multiple document interface (MDI) windows, or layout 
windows. One of the fundamental ObjectWindows classes that implements OLE 
functionality, TOleWindow provides support for embedding objects in a compound 
document application. 


Frame windows 

A frame window, which is actually an application’s main window, has the ability to 
contain other client windows and also support UI elements such as menus and icons. 
Serving as main windows of MDI-compliant applications, MDI frame windows manage 
multiple documents or windows in a single document (SDI) application. 
ObjectWindows also provides OLE support for both SDI and MDI applications. A 
floating frame window provides the same functionality but lets you position the 
window anywhere within the parent window. 


e TFrameWindow adds special functionality designed to simplify the managment of 
main windows. 


e TFloatingFrame, derived from TFloatingFrame and TTinyCaption, provides the 
functionality of a frame window enhanced with a tiny caption bar. 


e TMDIChild defines the behavior of MDI child windows. 


e TMDIFrame provides support for frame windows designed to be used as MDI 
windows. | 7 


e TOleFrame provides OLE support for the main window of an SDI application. 
¢ TOleMDIFrame provides OLE support for the main window of an MDI application. 


Mix-in window classes such as TLayoutWindow and TClipboardViewer add the special 
functionality of layout capabilities and clipboards to the main window classes. Use 
TLayoutWindow to design the placement of a window on the screen and 

TClipboard Viewer to view the data shared between applications. 


Decorated windows 

Multiply inherited from TFramewindow and TLayoutWindow, decorated window classes 
let you add decorated control bars, and status bars to the frame of a window and adjust 
the child window to accommodate the placement of these decorations. 


e TDecoratedFrame is basically a frame window with added decorations. 
e TDecoratedMDIFrame is an MDI frame window that supports decorations. 


Common dialogs 

TDialog lets you create specialized windows referred to as dialog boxes. Dialog boxes 
typically ask users for information about fonts, colors, files, printing options, or 
searching and replacing text. Depending on their purpose, dialog boxes can be either 
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modal, those which prevent a user from selecting other windows, or modeless, those 
which permit a user to select other windows. 


You can create your own customized dialog boxes or use one of the ObjectWindows 
classes that encapsulates Windows’ common dialog boxes. The following common 
dialog classes are derived from TCommonDialog which is itselt derived from TDialog, the 
base dialog box class. | 


¢ TChooseFontDialog objects represent modal dialog boxes allow font selection, style, 
point, size, and color. 


¢ TChooseColorDialog objects joncceal modal dialog — that allow color selection 
and custom color adjustment. 


¢ TOpenSaveDialog is the base class for modal dialog boxes that let you open and save a 
file under a specified name. 


e TPrintDialog displays a modal print or a printer setup dialog box. 


° TFindReplaceDialog is the base class for modeless dialog boxes that let you search for 
and replace text. 


Controls 

The control classes support standard Windows controls such as list boxes, combo boxes, 
group boxes, check boxes, scroll bars, buttons, radio buttons, edit controls, and static 
controls. 


Although most windows come with scroll bars already installed, you can use TScrollBar 
to create a standalone vertical < or horizontal scroll bar, for example, as a dialog box 
control. 


‘Unlike standard Windows controls, ObjectWindows supports widgets, specialized 
controls written entirely in C++. The widget classes ObjectWindows provides include 
support for sliders, controls that are used for providing nonscrolling position 
information, and gauges, controls that provide duration or analog information about a 
particular process. 


e TSlider defines the basic behavior of sliders. 
THSlider implements horizontal sliders. 

TVSlider implements vertical sliders. 

TGauge defines the basic behavior of gauge controls. 


Gadgets 
_ TGadget is the base class for several derived classes that support gadget eG that 
belong to a gadget window, have borders and margins, and their own style attributes. 
Derived from TWindow, TGadgetWindow maintains a list of gadgets, controls the aispley, | 
_ of the gadgets, and sends the necessary messages to the gadgets. 


Additional gadget classes derived from TGadgetWindow such as TToolBox, TMessageBar, 
TStatusBar, and TControlBar manipulate gadgets in different ways so that you can 
enhance a bar or tool box attached to a frame window. 


e TToolBox lets you place a set of gadgets in a matrix of columns and rows. 
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e TMessageBar implements a message bar with one text gadget. 


e TStatusBar lets you include a text gadgets and different border styles in a 
status bar. 


¢ TControlBar implements a control bar that seavides a set of buttons on a bar ina 
frame window. 


Menus 
TMenu and its derived classes let you construct, modify, and create menu objects. The 
classes derived from TMenu include 


e TPopupMenu lets you add a popup menu to an existing window or popup menu. 
e TSystemMenu creates a system menu object. 


Module management classes 


Derived from TModule, TApplication supplies functionality common to all 
ObjectWindows applications. Classes derived from TApplication have the ability to 
create instances of a class, create main windows, and process messages. TModule defines 
behavior shared by both library (DLL) and application modules. Virtually derived from 
TModule, TBiVbxLibrary lets you add Visual Basic (VBX) controls to your application. 


Doc/View classes 


Doc/View class support the Doc/View model, a system in which data is contained in 
and accessed through a document object, and displayed and manipulated through a 
view object. Any number of views can be associated with a particular document type. 
Various classes control the flow of information within this system. Several classes also 
provide support for OLE’s compound document and compound file structure within 
the Doc/ View model. | 


TDocManager is the base class designed to handle documents, templates, messages and 
so on. 


e TDocument is an abstract base class that serves as an interface between the document, 
its views and its document manager. 


e TStorageDocument supports OLE’s compound file structure and lets you create 
compound documents with embedded objects. 


e TOleDocument implements the document half of an OLE-enabled Doc/View 
application. 


¢ TView is the base class that displays the document’s data and gets user input. 
e TListView supports views for list boxes. 


e TOleView supports the view half of an OLE-enabled Doc/View application. 
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Printer classes 


TPrinter, TPrintout, and TPreviewPage provide various qncion that make it easy for 
you to set up a printer dialog box, view a document i ina print preview window, and 
print a document. 


e TPrinter represents the aad printer device. 7 
e TPrintout represents the physical printed document sent to the printer 
e TPreviewPage oe a page of a document in a print preview window. 


Graphics classes" 


ObjectWindows GDI classes encapsulate Windows’ poe Device Interface (GDP) to 
make it easier to use device context (DC) classes and GDI objects. The GDI library 
supports device independent drawing operations using DIBS (device independent 
bitmaps). 


DC classes 

Instead of drawing directly on a device (like the s screen or a printer), you can use GDI 
classes to draw on a bitmap using a device context (DC). A device context is a structure 
that contains information about the drawing attributes (pens, brushes, text color, and so 
on) of a particular device. DC classes support a variety of device context operations. 


¢ TDC is the root class for GDI DC wrapper classes. 


e¢ TWindowDC and its derived classes such as TClientDC and TScreenDC provide access 
to the area owned by a window. | 


e TCreatedDC and its derived classes provide access to various DCs that are created 
and deleted such as memory and print DCs. 


GDI classes 
ObjectWindows graphics library contains several classes that you can use to create 
DIBS, brushes, palettes, pens, and other drawing tools. 


¢ TGdiBase is the private base class from which TGDI Object, Tlcon, TCursor, and TDib 
are derived. 


_ © TGDIObject is a base class for several other GDI classes that support drawing tools. | 


e TDib encapsulates the creation of structures containing format and palette 
information. | 


e TCursor encapsulates GDI cursor objects. 


Validator classes 


-TValidator forms the base class for several ObjectWindows classes that encapsulate 
validation objects. The following derived classes make it easy for you to add data 
validation to your applications. 
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e TFilterValidator and its derived class, TRangeValidator, check an input field as the user 
types data into the field in order to determine the validity of the entered data. 


e TPXPictureValidator compares user input with a picture of a data format. 


e TLookupValidator compares a string typed by a user with a list of acceptable values. 


Exception handling classes 


Exception handling classes provide various functions that help you write error-free 
ObjectWindows applications. TXBase is the base class for all ObjectWindows and 
ObjectComponents classes. Derived from the TXBase class, TXOwl is the base class for 
the following ObjectWindows exception classes: 


e TXCompatibility is included for backward compatibility with ObjectWindows 1.0 
code. 


¢ TXOutOfMemory describes exceptions that arise from out of memory conditions. 


e Nested exception classes such as TXInvalidMainWindow, TXInvalidModule, 
TXWIndow, TXMenu, TX Validator, TXGdi, and TXPrinter describe specific error 
conditions such as those that occur when a main window, a module, a menu object, a 
validator object, a GDI object, or a printer device context is invalid. 


Command enabling classes _ 


Although several ObjectWindows classes process commands, there are three classes 
specifically devoted to enabling and disabling the commands available to an 
application. 


¢ TCommandEnabler is the base class from which BUCH RASCH AUE! and 
TMenulItemEnabler are derived. 


e TButtonGadgetEnabler enables and disables button gadgets. 


¢ TMenultemEnabler enables and disables menu options and places check marks by 
menu options. 


ObjectSupport library classes 


ObjectSupport classes provide various services that help you design your 
ObjectWindows application. For example, the class TLocaleString localizes OLE 
registration information required for containers and servers. These classes include the 
following groups: 


e Mathematical classes such as TPoint, TSize, and TRect that define screen coordinates 
and properties of rectangles. 


e Registration and localization classes such as TRegList and TLocaleString ene the 
process of registering OLE containers and servers. 


e Document template classes that make it easier to design Doc/ View ieee 
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The slivers table lists the files included i in the Object Support Library (..\OSL 
directory). 


Table 1.1 Summary of the ObjectSupport library files 


. ’ 8 
windows.h definitions, and deals with BOOL data 


| types. | 
doctpl.h TDocTemplate Creates the Doc/View classes. 
TDocTemplateT<D,V> __ Registers the associated document and view 
classes. 
except.h TXBase Base exception-handling alate for ObjectWindows 
and ObjectComponents classes. 
geometry.h TDroplnfo _ Supports file name drag and drop operations. 
TPoint, TSize, TRect Mathematical classes. 
TPointer | Provides exception-safe pointer manipulation. 
TProcinstance A Win16 support class. 
TResld | A resource ID. 
locale.h TLocaleString Localizable substitute for char’. 
TRegItem An item for the system registry. 


TRegList | List of registration items. 


ObjectWindows Libraries 
The following tables list the ObjectWindows static and dynamic libraries, their uses, and 


the operating system under which the library is available. These files are in yous library 
directory. | 


The name of the OWLWx.LIB file varies, depending on several factors—whether you 
are building a small, medium, or large memory model application or a WIN16 or 
WIN3SB2 application. For example, if the application is built for a 16-bit, small memory 
model, the name of the library file is OWLWS.LIB. If you’re building a flat model 
WIN322 application, the name of the library file is OWLWF.LIB where "F" indicates a flat 
model application. If runtime diagnostics are enabled, ObjectWindows adds "D" to the 
name of the libary. | 


Different versions of these files are ncuded on your installation disk. If the diagnostic 
files are not shipped, you can build these files by adding the switch -DDIAGS to the 
ObjectWindows makefile located in one EXAMPLES pas 


Table 1.2 | Summary of static libraries 


OWLWS.LIB Winl6 | 16-bit small model 
~OWLWMLLIB Winl6 | 16-bit medium model 
OWLWL.LIB Win16 16-bit large model 
OWLWLLIB Winl6é 16-bit import library for OWL250.DLL 


OWLDWS.LIB Win16 16-bit diagnostic small model 
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ae 12 ead of static libraries ee, 

Cnn LIB | aE ” 16-bit spec miedilint model. — 
OWLDWL.LIB Winl6 16-bit diagnostic large model 

OWLDWILILIB Winl6 16-bit diagnostic import library 

OWLWIU.LIB Win16 16-bit large static for user .DLL 

OWLWLU.LIB Winl6 16-bit import static for user .DLL 

OWLWFE.LIB Win32, Win32s 32-bit library 

OWLWFLLIB Win32, Win32s 32-bit import library for OWL250F.DLL 
OWLDWE.LIB ~—- Win32, Win32s_~—32-bit diagnostic library | 
OWLDWELLIB Win32, Win32s 32-bit diagnostic import library 


The dynamic-link library (DLL) versions of ObjectWindows are contained in the \BIN 
subdirectory of the installation. The following table lists the DLL names and uses, and 
the operating system under which each library is available. 


Table L 3 


‘File: name App! 
OWL250. DLL Win 16 
OWL250F.DLL Win 32 
OWL250D.DLL Win 16 
OWL250DF.DLL Win32 


ecules ol ayoamie link panies 


| on = library 


32-bit dynamic library 
Diagnostic version of 16-bit dynamic library 
Diagnostic version of 32-bit dynamic library 


Compiler options for building and using ObjectWindows libraries 


You need to use different compiler options depending on whether you are building or 

~ using ObjectWindows DLLs or static libraries. Unless you specify otherwise, 
ObjectWindows makes several assumptions about the default values for system 
platforms and memory models. That is, ObjectWindows assumes that the platform is 
winl6 unless MODEL is explicitly set to "f," in which case ObjectWindows assumes that 
the platform is Win32. The default MODEL setting is "d," where "d" indicates that you 
are building the DLL version of an library. 


The following table lists the combinations of SYSTEM and MODEL settings you can use 
to build the specified target applications. 


Table 1.4 = Target applications and compiler options 

16-bit Windows small Ewe static version WINI16 S 
16-bit Windows medium model static version WINI16 m 
16-bit Windows compact model static version WIN16 C 
16-bit Windows large model static version WIN16 l 
16-bit Windows large model DLL WIN16 d 
32-bit Windows static version WIN32 f 
32-bit Windows DLL WIN32 d 
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Building ObjectWindows | libraries 

If you are building ObjectWindows DLLs and libraries, you need to use several pre- 
defined macros. For example, defining the make macro USERDLL builds 
ObjectWindows for use ina user DLL and adds the suffix, "U" to the name of the library. 
The preprocessor macro _BUILDOWLDLL, which must be defined to build the 
ObjectWindows DLL, sets the values for the COOWLCLASS, OWLDATA, OWLFUNC 
macros. 


The following table lists the make options you need to use if you are building either 16- 
or 32-bit ObjectWindows. You can specify the system model as either s (small), m 
(medium), | (large), f (flat), or d (DLL). The make options you set are then responsible’ _ 
for generating the specified preprocessor macro, which, in turn, generates the indicated _ 
values for the OWLCLASS, OWLDATA, and OWLFUNC macros and builds the 
appropriate library. For an example of how these settings are used, see the makefile in 

the \SOURCE\OWL directory or owldefs.h in the INCLUDE\OWL directory. 


Table 1.5 


Summary of options for building an ObjectWindows static or dynamic library 


ObjectWindows DLL | | 
16-bit EXE MODEL = d _BUILDOWLDLL Allare defined |= OWLWLLIB 
as ___ export. 
32-bit EXE or DLL MODEL = d | _BUILDOWLDLL All are defined §£OWLWFLLIB 
_~DWIN32 as __export 
MODEL = d _BUILDOWLDLL All are defined OWLWIU.LIB 
-D USERDLL ae exper: 
16-bit DLL. | 
ObjectWindows static library | 
16-bit EXE MODEL = s or m or | Nothing Nothing OWLWS.LIB 
| OWLWM.LIB 
a 4 | | OWLWL.LIB 
32-bit EXE or DLL MODEL = f Nothing Nothing OWLWE.LIB 
-DWIN32 | | | 
16-bit DLL MODEL = 1 Nothing ~ Nothing OWLWLU.LIB 
—DUSERDLL | 


Using ObjectWindows libraries 


This table lists the make options you need to specify if you are using either 16- or 32-bit 
ObjectWindows applications. You can specify the memory model as either s (small), m 
(medium), | (large), f (flat), or d((DLL). (Keep in mind that the make options | 
SYSTEM=WIN32 and -DWIN32 are the same.) The make options you set are then 

_ responsible for generating the specified preprocessor macro, which, in turn, generates 
the indicated values for the OWLCLASS, OWLDATA, and OWLFUNC macros and 
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builds the appropriate library. For an example of how these settings are used, see 
MAKEFILE.GEN in the \OWL\EXAMPLES directory. 


Table 1.6 § Summary of options for using an ObjectWindows static or dynamic library 
If you are using an: __ Use these Make options: Preprocessormacro _OWLFUNC Libraries 
ObjectWindows DLL | 
16-bit EXE MODEL = d -OWLDLL All are defined OWLWL.LIB 
| as__import 
32-bit DLL MODEL = d -_OWLDLL All are defined OWLWEL.LIB 
~DWIN32 as __import 
16-bit DLL MODEL = d ~OWLDLL All are defined OWLWIU.LIB 
as __ import 


ObjectWindows static library 


16-bit EXE MODEL = s or m or | Nothing Nothing OWLWS.LIB 
OWLWM.LIB 
OWLWL.LIB 
32-bit EXE or DLL MODEL = f Nothing : Nothing OWLWE.LIB 
—DWIN32 
16-bit DLL MODEL = 1 Nothing Nothing OWLWLU.LIB 


The following table lists the makefile and compiler options for the OWLFARVTABLE 
macro, which moves ObjectWindows virtual function tables (vtables) out of the 
DGROUP of the data segment and stores them in the code segment. 


Table 1.7 | Compile options for OWLCLASS macro 


es S _. a o 

BIDSFARVTABLE modifier when static models are used. 
_RTLFARVTABLE 
_FASTTHIS Doesn’t apply Adds _fastthis to the OWLCLASS macro. 


The ObjectWindows header files 


Header files contain prototype declarations for class functions, and definitions for data 
types and symbolic constants. 


Table 1.8 = Summary of header files 


Directory of \INCLUDE\OWL 


appdict.h TAppDictionary Contains a set of assoications between an application and 
a process ID. 

applicat.h TApplication Controls the basic behavior of all ObjectWindows 
applications. 
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- Table 1.8 


| Summary of header files (continued) 


bitmapga.h | 
bitseth 


button.h 
buttonga.h 
celarray.h 
checkbox.h 
chooseco.h . 
choosefo.h 
clipboar.h 


| clipview.h 
color.h 


combobox.h 
commdial.h 
compat.h 


control.h 
controlb.h 


controlg.h 
deh 


decframe.h 
decmdifr.h 


dialog.h 


: dispatch.h 
docmanag.h 


doctpL.h 


docview.h 


TBitmapGadget 


TBitSet | 
TCharSet 
TButton 
TButtonGadget 
TCelArray 
TCheckBox 
TChooseColor 
TChooseFont 

_ TClipboard 


TClipboardViewer 
TColor 


TCombobox 


TCommonDialog 


TControl | 
TControlBar 


TControlGadget 


TBandInfo, TClientDC, 
TCreatedDC, TDC, 
TDesktopDC, TDibDC TIC, 


TMemoryDC, TMetaFileDC, 


TPaintDC TPrintDC, 
TScreenDC, TWindowDC 


TDecoratedFrame 
TDecoratedMDIFrame 
TDialog 


TDialogAttr 


TDocManager 


TDocTemplate 
TDocTemplateT 
TDocument, TView, 


TWindow View, TStream, 
TInStream, TOutStream 
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A set including pues no more than 256 items managed by 
bits. 


Sets or clears one or more bits. 

A set of characters | 

Creates different types of button controls. 

Creates button gadgets that can be clicked on or off. 
Creates an array of bitmap cels. 

Represents a check box control. | | 
Represents modal dialog boxes that allow color selection. 
Represents modal dialog boxes that allow font selection. 


Contains functions that control how Serres data is 
handled. 


Registers a TClipboard Viewer as a Clipboard viewer. 


Contains functions used to simplify standard Windows 
color operations. 


Creates combo boxes or combo box controls in a window, 
and class TCcomboBoxData, which is used to transfer data 


~ between combo boxes. 


Abstract base class for TCommonDialog objects. 


Defines functions and constants used internally by © 
ObjectWindows. 


Used to create control objects in derived cee 


Implements a control bar that provides mnemonic access 
for its button gadgets. 


Allows controls to be placed in a gadget window. 
GDI DC wrapper classes that create DC objects. 


Creates a client window into which decoradors can be 
placed. 


Creates a frame object that supports decorated child — 
windows. 


Creates modal and modeless dialog box interface 
elements. 


Holds the dialog box diedshe s attributes. 


_ Defines dispatch functions designed to crack Windows 


messages. 


Creates a document manager object that manages the 
documents and templates. 


Creates the templates. 
Registers the associated document and view classes 


Create, destroy, and send messages about document 
views. 


Define streams for documents. 


Table 1.8 


a rR 
editfile.h 
editsear.h 


editview.h 
eventhan.h 
except.h 


filedoc.h 
findrepl.h 


floatfra.h 
framewin.h 
gadget.h 


gadgetwi.h 


gauge.h 
gdibase.h 
ediobjec.h 


geometry.h 


groupbox.h 


inputdia.h 
layoutco.h 
layoutwi.h 


listbox.h | 


TEditFile 
TEditSearch 


TEditView 
TEventHandler 
TXBase 

TXOwl 
TXCompatibility 
TXOutOfMemory 
TStatus 


TFileDocument 
TFindDialog, 
TFindReplaceDialog:: 


TFloatingFrame 
TFrameWindow 


TGadget 


TGadgetWindow 
TGadgetWindowFont 
TSeparatorGadget 
TGauge 

TGdiBase 
TGdiObject 

TPen, TBrush, TFont 
TPalette, TBitmap, 
TIcon, TCursor, TDib, 
TRegion 

TPoint, TSize, TRect 
TDropInfo 
TProcinstance 
TPointer 

TResId 

TGroupBox 


TInputDialog 
TLayoutConstraint 


_TLayoutMetrics 


TLayoutWindow 


TListBox 
TListBoxData 


lass definition ees 
a eee 


Summary of header files (continued) 


reates an edit control interface element. 


Creates a file editing window. 


Creates an edit control that responds to sere ne 
replace commands. 


View wrapper for TEdit. 
Used to derive class capable of handling messages. 


Base exception-handling class for ObjectWindows and 
ObjectComponents classes. 

Base exception-handling class for ObjectWindows 
classes. 

Included for backward compatibility. 

Describes an out-of-memory exception. 

Describes a status exception. 

Opens and closes document views. 


These classes create and define the attributes of modeless 
dialog boxes that respond to search and replace 
commands. 


Implements a floating frame within a parent window. 


Controls window-specific behavior such as keyboard 
navigation and command processing. 


Creates gadget objects that belong to a gadget window 
and have specified attributes. 


Maintains a list of tiled gadgets for a window. 
Defines the font used in gadget windows. 
Creates a separator between gadgets. 
Establishes the behavior of gauge controls. 
Abstract base class for all GDI classes. 

Base GDI class. 

These classes create specified GDI objects. 


Mathematical classes. 

Supports file name drag and drop operations. 
A Win16 support class. 

Provides exception-safe pointer manipulation. 
Creates a resource ID. 


Creates a group box object that represents a group box 
element in Windows. 


Creates a generic dialog box that accepts text. 
Creates layout constraints. 


Contains the layout constraints used to define the layout 
metrics for a window. 


Provides layout options for a window. 


Creates a list box object. 
Used to transfer the contents of a list box. 
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Table 1.8 


Summary of header files (continued) 


locale.h 
mdi.h 


mdichild.h 


menu.h 


messageb.h 
metafileh 
module.h 


oledoc.h 
olefacto.h 


olefacto.h 


oleframe.h 


sence. 


oleview.h 
olewindo.h 
opensave.h 
owlall.h 
owlcore.h 
owldefs.h 


owlpch.h 


preview.h 


printdia.h 
printer.h 


radiobut.h 
scrollba.h 


scroller.h 
signatur.h 


TLocaleString 


TMD!IClhient 
TMDIFrame . 


_ TMDIChild 
_TMenu, TPopupMenu, 


TSystemMenu 
TMenuDescr 


TMessageBar 


-TMetaFilePict 


TModule 


TOleDocument 
TAutoFactory<> 


TOleFactory<> 


TOleFrame 
TOleMDIFrame 


TOleView 
TOleClientDC 
TOpenSave 


TPreviewPage 
TPrintPreviewDC 
TPrintDialog 
TPrinter 
TPrintout 
TPrinterAbortDlg 
TRadioButton 


TScrollBar 
TScrollBarData 


TScroller 
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Localizable substitute for char*. 

Manages MDI child windows. | 

The main window of MDI-compliant applications. 
Defines the behavior of MDI child windows. 
Create menu objects. 

Base menu class. — 

A menu bar with groups. 


Implements a message bar. 
A wrapper class used with TMetaFileDC. 


Defines the basic behavior for ObjectWindows libraries 
and applications. 


Implements the Document half of the Doc/View pair. 


Template class that supports component create callbacks 
for automated OLE-enabled applications. 


Template class that supports component create callbacks 
for Doc/View and non-Doc/View OLE-enabled 
applications. 


Supports OLE-enabled main windows for SDI 
applications. 


Supports OLE-enabled main windows for MDI 
applications. 


Supports the View half of the Doc/View pair. _ 
Translates between two different coordinate systems. 
Base class for modal open and save dialog boxes. 
Include file for all of the ObjectWindows classes. 
Include file for the core ObjectWindows classes, 


Includes definitions of macros used by all 
ObjectWindows programs. 


Contains definitions of macros, data, and functions used 
by ObjectWindows. | 


Displays a document page in a print preview window. 
Maps printer device coordinates to screen coordinates. 
Displays a modal print or print setup dialog box. 
Represents the printer device. | 

Represents the printed document. 

Represents the printer-abort dialog box. 

Create a radio button control. 

Represents a vertical or horizontal scroll bar control. 


Contains the values of the thumb position on the scroll _ 
bar. a ? 


Implements automatic window scrolling. 


Defines the message cracking signature templates used 
by ObjectWindows event-handling functions. 


Table 1.8 §= Summary of header files (continued) 


Use 


sliderh 


_ Static.h 
statusba.h 
stedoc.h 
textgadg.h 
tinycapt.h 
toolbox.h 


uihandle.h 
validate.h 


vbxctl.h 


version.h 


window.h 


windowev.h 


TSlider 

THSlider 

TVSlider 

TStatic 

TStatusBar 
TStorageDocument 
TTextGadget 
TTinyCaption 
TToolBox 


TUIHandle 

TValidator, 
TPXPictureValidator 
TFilterValidator, 

TRange Validator, 
TLookupValidator, 
TStringLookupValidator 
TVbxControl 
TVbxEventHandler 
TBIVbxLibrary. 


TWindow 


Defines the basic behavior of sliders, 


A horizontal slider. 

A vertical slider. 

Create a static control in a window. 

Constructs a status bar. 

Supports compound file structure mechanisms. 
Construct a text gadget object. 

Produces a smaller caption bar for a window. 


Creates a toolbox object with a specified number of rows 


and columns. 

Defines and draws UI handles. 
Base validator class. 

Picture validator. 

Filter validator. 

Range validatator. 

Lookup validation. 

String validation. 

Interface for VBX controls. 
Handles events from VBX controls. 
Loads and initializes BIVBXxx.DLL. 


Defines the internal version number of the 
ObjectWindows library. 


Provides window-specific behavior and encapsulates 
many of the Windows API functions. 


Defines event handlers and response table macros for 
Windows messages. 


The ObjectWindows resource files 


The ObjectWindows resource files define resource and command IDs. 


Table 1.9 
7 File na 


Directory of \INCLUDE\OWL 


docview.rh 


edit.rh 
editfile.rh 


editsear.rh 


editview.rh 
except.rh 
inputdia.rh 


Summary of resource files 


Defines resource and command IDs to use with docview.h and 


docview.rc. 


Defines command IDs to use with edit.h. 


Defines resource and command IDs to use in editfile.rc and 


editfile.h. 


Defines resource and command IDs to use in editsear.rc and 


editsear.h. 


Defines accelerator and menu IDs to use with TEditView. 


Defines string resource IDs to use with except.h and except.re. 


Defines resource [Ds to use with inputdia.rc and inputdia.h. 
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Summary of resource files (continued) 


~ Table 1.9 


listview.rh Defines resource and command IDs to use with listview.h.. 
locale.rh Defines localization resource IDs.. | 
mdi.rh Defines resource and command IDs to use with mdi.h. 
oleview.rh_- Defines resource IDs to use with OLE-enabled views. 
printer.rh Defines resource IDs to use with printer.rc and printer.h. 
slider.rh Defines resource IDs to use with slider.h. 

_ statusba.rh Defines resource IDs to use with statusba.h 
validate.rh Defines resources to use with TValidator and derived classes. 
window.th Defines command IDs to use with window.h. 


The ObjectWindows data types 


ObjectWindows data types have been updated to use more portable type names. The 
following table lists the Windows API type names, the underlying C type definitions, 
and the new ObjectWindows type names. To ensure that these new types are used 
correctly, be sure to include the ObjectWindows header files before any Windows files, 
such as windows.h, in your application files. The new C++ type, which maps a nonzero 
value to TRUE, lets you assign an integer to a bool type. You can then compare this 
Boolean value to TRUE . 


Table 1.10 New ObjectWindows data types 


char Used when 8 bit signed value is needed 
BYTE unsigned char Always 8 bits 
WORD unsigned short Always 16 bits 
int int | 16 or 32 bits depending on the platform 
UINT unsigned int uint 16 or 32 bits depending on the platform 
LONG long long, int32 Long (Could be 64 bits on some platforms) 
ULONG unsigned long ulong, int32: Long (Could be 64 bits on some platforms) 
long int32 Always 32 bits 
DWORD unsigned long uint32 Always 32 bits 
BOOL int bool New C++ type if available; otherwise, 
emulated using an enum. © 
TRUE 1 true 
FALSE 0 false 
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ObjectWindows library reference 


This chapter alphabetically lists the ObjectWindows classes, data members, member 
functions, macros, constants, and data types. The header file that defines each entry is 
listed opposite the entry name. Class members are grouped according to their access 
specifiers, either public or protected. Within these categories, data members, then 
constructors (and the destructor, if one exists), and member functions are listed 
alphabetically. 


Because many of the properties of the classes in the hierarchy are inherited from base 
classes, only data members and member functions that are new or redefined for a 
particular class are listed. Private members are not listed. If any response table entries 
exist, they are also listed. The cross-referenced entries provide additional information 
about how to use the specified entry. The first sample entry illustrates this format. 


To find information about a particular inherited member function, use the inheritance 
diagram included at the beginning of each class. The inheritance diagram shows the 
virtual overridden functions that form the interface of the class, excluding 
TEventHandler and TStreamableBase, from which all classes are inherited. For a list of all 
the inherited as well as overridden virtual functions, see the online Help. 


TBird class [sample] bird. 


Type definitions 


This section alphabetically lists all typedefs and enums defined within a class. 


typedef unsigned short TOwlld 
typedef unsigned short TOwlld; | | 
This text explains what this typdef contains, and how you use it. 


See also Related data members, member functions, classes, constants, and types 
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‘TBird class [sample] 


| Public data members 


This section alphabetically lists all public data members and thet deciiraGons: and | 
explains how they a1 are used. 3 


-anOwiBeak 
anOwlType anOwlBeak; 

_anOwl!lBeak is a data member that holds information about this sample class. This text 
explains what anOwlBeak contains, and how you use it. 


See also Related data members, member functions, classes, constants, and types 


anOwlWing 
anOwlType anOwilWing; | 
anOwlWing is another public data member. 


Public constructor and destructor 


This section lists any public constructors and destructor for this class. Classes can have 
more than one constructor; they never have more than one destructor. 


Constructor 
TBird(anOwlType aParameter); _ 
Constructor for a new sample class; sets the anOw!Beak data member to aParameter. 


Destructor. 
~TBird; | 
Destructor for a new sample class; destroys the TBird object. 


Public member functions 


This section alphabetically lists all public member functions that are either newly 
defined for this class or that are redefined inherited member functions. The description 

— includes the purpose of each parameter and the return value of the function. If a 
function overrides a virtual base class function, the text specifies this: 


The inline keyword isn’t provided because it doesn’t affect usage. 
EvGetDigCode 

UINT OwlHoot(); 

Responds to WM_GETDLGCODE messages. 

OwlHoot 

void OwlHoot(); 


The OwlHoot member function causes the sample class to perform some action. This 
function overrides the function OwlHoot in its base class, TParent. 


See also TParent::OwlHoot 


OwlSleep | 
virtual int OwlSleep(int index); 
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TBird class [sample] 
The OwlSleep function performs another action and overrides the function OwlSleep in 
its base class, TParent. 


Seealso TParent::OwlSleep 


Protected data members 


This section alphabetically lists all protected data members and their declarations, and 
explains how they are used. 


anOwlFeather 
anOwlType anOwiFeather; 
anOwlFeather is a protected data member that holds information about this sample class. 


Seealso Related data members, member functions, classes, constants, and types 


Protected constructors 


Constructor 
TBird(anOwiType bParameter); 
If the class has a protected constructor, it is listed here. 


Protected member functions 


This section lists all protected member functions. 


OwilCry 
BOOLEAN OwiCry: 
The OwlCry member function causes the sample class to perform some action. 


Seealso TSomethingElse:;OwlCry 


Zatslt 
virtual int ZatsIt(int index); 
The ZatsIt function performs a particular function in class TBird. 


Response table entries 


The TBird response table contains this predefined macro for the EV_xxxx messages and 
calls this member function: 


Member. uw 
‘EV “WM “GETDLGCODE > ~ EVGetDigCode 
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— BF_xxxx button flag constants. 


~ Check box and radio one objects use the button flag constants to indicate the state ofa _ 
selection box. 


Table 2.1 Button flag constants 


BF_CHECKED Item is checked. 
BF_GRAYED Item is grayed. 
BF_UNCHECKED Item is unchecked. 


See also ia TCheckbox::SetCheck | 


oN) _xxxx button message constants windows.h 


Mouse and radio button objects use the button message constants to fndicaid the state of 
a button. 


Table 2.2 Button message constants 


BN_DISABLE Message sent when a button is disabled 


BN_DOUBLECLICKED Message sent when the user double-clicks a button. 

BN_HILITE Message sent when the user highlights a button 

BN_PAINT Message sent when a button needs to be repainted 

BN_UNHILITE Message sent when the highlighting needs to be removed from a button . 


See also TRadioButton::BNClicked 


CBN_xxxx combo box message constants windows.h 
Combo box objects use these message constants to indicate the state of the combo box. 


Table 2.3 | Combo box message constants 


essag 


CBN_DBLCLK Message sent when the user double-clicks a text string in the combo box 

CBN_DROPDOWN Message sent when the list box of a combo box drops down 

CBN_._EDITCHANGE Message sent when the user changes text in the edit control portion of a 
. combo box | 

CBN_EDITUPDATE _ Message sent when edited text is going to be displayed 

CBN_ERRSPACE Message sent when the combo box is out of memory 


CBN_KILLFOCUS © Message sent when the combo box loses the input focus 
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CM_xxxx edit constants 


Table 2.3. | Combo box message constants (continued) 


CBN_SELENDCANCEL Message sent when the user's initial selection needs to be cancelled because 
the user has selected another control or closed the dialog box. 
CBN_SELENDOK Message sent if the user's selection is valid 
CBN_SETFOCUS Message sent when the combo box receives the input focus 
See also TComboBox 
CM_xxxx edit constants window.rh 


These command-based member functions are invoked in response to a particular edit 
menu selection or command. 


Table 2.4 Command-based constants 


CM_EDITCLEAR _TEdit:CMEditClear —_—Edit | Clear 
CM_EDITCOPY TEdit:;CMEditCopy Edit | Copy 
CM_EDITCUT — TEdit::CMEditCut Edit | Cut 
CM_EDITDELETE TEdit::CMEditDelete Edit! Delete 
CM_EDITPASTE TEdit::CMEditPaste Edit | Paste 
CM_EDITUNDO TEdit::CMEditUndo Edit | Undo 
CM_EXIT TWindow::CmExit File | Exit 


Seealso TEdit::CMEditClear, TEdit:;CMEditCopy, TEdit::CMEditCut, 
TEdit::CMEditDelete, TEdit::CMEditPaste, TEdit:;CMEditUndo, TWindow::CmExit 


These command-based member functions are invoked in response to open, close, print, 
and save commands. 


Table 2.5 Command-based constants 


CM_FILECLOSE - FilelClose —«™*”S 


CM_FILENEW TEditFile::CmFileNew File | New 
CM_FILEOPEN TEditFile::;CmFileOpen File | Open 
(CM_FILEPRINT File | Print 
CM_FILEPRINTERSETUP File | PrinterSetup 
CM_FILEREVERT TDocManager::CmFileRevert File | Revert 
CM_FILESAVE TEditFile::CmFileSave File | Save 
CM_FILESAVEAS TEditFile::CmFileSaveAs File |Save As 
CM_VIEWCREATE TDocManager::CmViewCreate File | View Create 
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CM_xxxx edit replace constants 


‘See also TEditFile: <CmFileN ew, TEditFile: CmFileOpen, TDocManager: CmFileRevert, 
TEditFile: a TEditFile:;CmFileSaveAs 


CM_ 00x edit replace constants 


editsear.rh © 


These command-based member functions are invoked when the corresponding find 
and replace command is received. 


Table 2.6 


Command-based constants 


CM_EDITFINDNEXT 
CM_EDITREPLACE 


TEditSearch::CMEditFindNext 
TEditSearch::CMEditReplace 


Edit | Find | Next 
Edit | Replace 


Seealso TEditSearch::CMEditFind, TEditSearch: -CMEditFindNext, 
TEditSearch::;CMEditReplace 


CIM_xxxx edit view constants 


oleview.rh 


These command-based view functions are invoked in response to menu and accelerator 
key commands. The Edit | Verbs selection refers to one of the OLE-specific menu 
commands, such as Edit or Open. 


Table 2.7 


Command-based constants 


CM_EDITPASTELINK 
CM_EDITINSERTOBJECT 
CM_EDITLINKS 
CM_EDITOBJECT 
CM_EDITFIRSTVERB 
CM_EDITLASTVERB 
CM_EDITCONVERT 


OW:: 


P 


~ TOleWindow::CMEditPasteLink 


TOleWindow::CMEditInsertObject 
TOleWindow::CMEditLinks 
TOleWindow::CMEditObject 
TOleWindow::EvCommandEnable 
TOleWindow::EvCommandEnable 
TOleWindow::CMEdit 
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Pp 
Paste | Link 


Insert | Object 
Edit | Links 
Edit | Object 
Edit | Verbs 
Edit | Verbs 
Edit | Convert 


CM_xxxx MDI constants 


These MDI functions are invoked when the corresponding MDI command message is 
received. | 


Table 2.8 Command message constants 


Constant _ Beas ‘Member function — : : eo é Menu equivalent — oe 
CM_ARRANGEICONS | TMDiIClient: Cue on Window | Arrange Icons _ 
CM_CASCADECHILDREN TMDi!IClient::CmCascadeChildren Window | Cascade 
CM_CLOSECHILDREN TMD!1Client::CmCloseChildren Window | Close All 
CM_CREATECHILD TMDyiIClient::CmCreateChild 

CM_TILECHILDREN TMDIClient::CmTileChildren Window | Tile 
CM_TILECHILDRENHORIZ TMD!Client::CmTileChildren Window | Tile 


Seealso TMDIClient::CmArrangelcons, TMDIClient::CmCascadeChildren, 
TMDIClient::CmCloseChildren, TMD!IClient::CmCreateChild, 
TMD!IClient::CmTileChildren 


Declares a response table in the class definition. To handle events for a class, you need to 
both declare a response table with this macro and define the response table using one of 
the DEFINE_RESPONSE_TABLE macros. For example, to declare a response table, use 
the following declaration, where the single parameter, Class, represents the name of the 
current class: 


DECLARE_RESPONSE_TABLE (Class) ; 


ObjectWindows' response tables define the relationship between a window message 
and a corresponding event-handling function. The description of TEventHandler has 
more information about how ObjectWindows associates a response table entry with the 
appropriate function. 


See also DEFINE _RESPONSE_ TABLE macros, END_RESPONSE_TABLE macro, 
TEventHandler class 


This macro defines an AppDictionary reference and object as needed for use in 
component DLLs and EXEs. Unless a user dictionary is specified, the macro defines the 
dictionary as OwlAppDictionary, which is a globally alata TAppDictionary. The macro 
is defined as follows: 


# define DEFINE_APP_DICTIONARY (AppDictionary) 


Seealso TAppDictionary 
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_ DEFINE_DOC_TEMPLATE_CLASS macro | ‘ 
DEFINE DOC TEMPLATE CLASS macro ~— doctpL.h 


Creates a document template. Takes three arguments: the name of the document class 

that holds the data, the name of the view class that displays the data, and the name of 
the template class, and then associates the document with one or more views. The 
following example illustrates how you can associate document and view classes with 
new template classes. 


| DEFINE _DOC_TEMPLATE_CLASS(TFileDocument, TListView, ListTemplate) ; 
DEFINE_DOC_TEMPLATE_CLASS(TFileDocument, TEditView, EditTemplate) ; 


See also TDocTemplate 


Defines a response table. Takes one plus x number of arguments: one is the name of the 
class that is defining the response table, and x is the immediate base class as well as any 
virtual base classes. Use the END_RESPONSE_TABLE macro to end the definition for 
the response table. Between the DEFINE_RESPONSE_TABLE macro and the 
END_RESPONSE_TABLE macro, insert the message response entries for the messages 
you want the class to handle. For example, 


DEFINE_RESPONSE_TABLE1(TMyClass, TWindow) 
EV_WM_PAINT, 
EV_WM_LBUTTONDOWN, 

END_RESPONSE_TABLE; 


In this example, EV_WM_PAINT and EV_WM_LBUTTONDOWN illustrate the 
message response entries for the class TMyClass derived from TWindow. These macros 
call the corresponding event-handling functions, EvPaint and EvLButtonDown, 
respectively. Note that response tables are sometimes defined, but have no entries. In 
such cases, the base class's response table entries are searched for the appropriate event- 
handling function. You can also associate more than one meas: with an event- 
handling function. 


The following table shows the form the DEFINE_RESPONSE_TABLE macro takes 
depending on the number of base classes. 


DEFINE_RESPONSE_TABLE(Class) 
DEFINE_RESPONSE_TABLE(Class, Base) 
DEFINE_RESPONSE_TABLE2(Class, Base1, Base2) 
DEFINE_RESPONSE_TABLE3(Class, Base1, Base2, Base3) 


WON FR © 


See also DECLARE RESPONSE _ TABLE macros, END__ RESPONSE TABLE macro, 
TEventHandler class | 
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DLGC_ xxxx dialog control message constants 


DLGC xxxx dialog control message constants windows.h 
Indicate the kind of input that the dialog manager needs to process. Returned by 
EvGetDlgCode. 
Table 2.9 Dialog control message constants 

Constant | Meaning ~~ : 

DLGC_BUTTON | Indicates a button 
DLGC_DEFPUSHBUTTON __ Indicates a default button 
DLGC_HASSETSEL Indicates a range of characters in an edit control 
DLGC_RADIOBUTTON Indicates a radio button control message 
DLGC_STATIC Indicates a static control 
DLGC_UNDEFPUSHBUTTON Indicates a non-default push button control 
DLGC_WANTALLKEYS Indicates all keyboard input 
DLGC_WANTARROWS Indicates the direction keys 
DLGC_WANTCHARS Indicates all key code messages 
DLGC_WANTMESSAGE Indicates all keyboard input can be passed on to the control. 
DLGC_WANTTAB Indicates the TAB key 


Seealso TButton::EvGetDlgCode, TCheckBox::EvGetDlgCode, TEdit::EvGetDlgCode, 
TListView::EvGetDlgCode, TSlider::EvGetDlgCode 


dimxxxx document manager mode constants docmanag.h 


Used by TDocManager to indicate if a document supports single or multiple open 
documents, and to indicate if it has file menu IDs. 


| dmMenu Sets IDs for file menu. 


dmMDI Supports multiple open documents. 
dmNoRevert Disables the File | Revert menu command. 
dmSaveEnable Enables File | Save menu command. 

dmSDI Does not support multiple open documents. 


Seealso ['DocManager::TDocManager 
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A nxxxx document message constants 


dmoox document message constants 


- docmanag.h 


Used by TDocManager to indicate that a document or view has been created or closed. 
You can set up response table entries for these messages using the EV_OWLVIEW or 
EV_OWLDOCUMENT macros. 


dnCreate A new document or view has been created. 


dnClose A document or view has been closed. 


See also TDocManager ‘TDocManager 


“dboox document template constants - 


locale.h 


Used by TDocument and T DocTemplate to create templates. Several constants are 
equivalent to the OFN_xxxx constants defined by Windows in commdlg.h. 


dtAutoDelete 


dtAutoOpen 
dtCreatePrompt 


dtDynRegInfo 
dtFileMustExist 


dtHidden 


dtHideReadOnly 
dtNewDoc 


dtNoAutoView 


dtNoReadOnly 
dtNoTestCreate 


(OFN_CREATEPROMPT) 


(OFN_FILEMUSTEXIST) 


(OFN_HIDEREADONLY) 


(OFN_NOREADONLYRETURN) 
(OFN_NOTESTFILECREATE) 
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Deletes the document when the last view 
is deleted. 


Opens a document upon creation. 
Prompts the user before creating a 
document that does not currently exist. 


Used to register a container or server for 
OLE 2 support. Indicates that the 
registration information table is dynamic 
not static. 


Lets the user enter only existing file 
names in the File Name entry field. If an 


invalid file name is entered, causes a 


warning message to be displayed. 


Hides the template from the user's 
selection. 


Hides the read-only check box. 


Creates a new document with no path 
specified. 


Does not automatically create the default 


view type. 


_ Returns the specified file as writeable. 


Does not perform document-creation 
tests. The file is created after the dialog 
box is closed. If the application sets this 
flag, there is no check against write 
protection, a full disk, an open drive 
door, or network protection. For certain 
network environments, this flag should 
be set. 


END RESPONSE TABLE macro 


Constant —SWindowsequivalent = = = Meaning 

dtOverwritePrompt | (OFN_OVERWRITEPROMPT) When the Save As dialog box is 
displayed, asks the user if it's OK to 
overwrite the file. 

dtPathMustExist (OFN_PATHMUSTEXIST) Allows only valid document paths to be 


entered. If an invalid path name is 
entered, causes a warning message to be 


displayed. 
dtProhibited (OFN_ALLOWMULTISELECT) Doesn't support these specified 
(OFN_ENABLEHOOK) Windows options 
(OFN_ENABLETEMPLATE) 
(OFN_ENABLETEMPLATEHANDLE) 
dtReadOnly (OFN_READONLY) Checks the read-only check box when the 
dialog box is created. 
dtRegisterExt Used to register a container or server for 
OLE 2 support. Registers an extension 
with this application. 
dtSelected Indicates the last selected template. 
dtSingleUse Indicates that the document is to be 
registered as a sing] use document. 
dtSingleView Provides only a single view for each 
document. 
dtUpdateDir Updates the directory with the directory 
specified in the dialog box. 


Seealso TDocTemplate::GetFlags, TLocaleString, TDocument class 


END_RESPONSE TABLE macro] ventana 


END_RESPONSE_TABLE; 
Indicates the end of a response table. For each class that contains a response table, add 
this macro to the class definition. 


See also DEFINE RESPONSE _TABLE macro 


EN_xxxx edit message constants windows.h 


Indicate the state of an edit control in various situations: after a user has changed text, 
when the edit control receives the input focus, and so on. 


Table 2.10 Edit message constants 


ENCE Message sent when the display is updated after changes have been made to the - 


edit control 
EN_ERRSPACE Message sent when the edit control is out of memory 
EN_HSCROLL Message sent when the user clicks the horizontal scroll bar 
EN_KILLFOCUS Message sent when the edit control is losing the input focus 
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EV xxxx macros — 


Table 2.10 Edit message constants (continued) 


~ EN _MAXTEXT __ Message sent when the text insertion is truncated 
EN_SETFOCUS Message sent when the edit control receives input focus _ 
EN_UPDATE Message sent when the edit control is going to display revised text 
EN_VSCHOLL Message sent when the user clicks the vertical scroll bar 
EV_ XXXX Macros Ae, —_ _ windowev.h 


Create response table entries that match events to member functions. 


EV_CHILD_NOTIPFY (id notifyCode,method) Handles child ID notifications (for example, 
button, edit control, list box, combo box, and 
scroll bar notification messages) at the child's 
parent window. Passes no arguments. 


EV_CHILD_NOTIFY_ALL_ CODES | | Passes all notifications to the response function. 


and passes the notification code in as an 
argument. 

EV_CHILD_NOTIFY_AND_CODE(id, notifyCode, Handles child ID notifications at the child's 

method) parent window and passes the notification code 

| as an argument. 
EV_COMMAND(id, method) | Handler for menu selections, accelerator keys, 
| and push buttons. 
EV_COMMAND_AND_ ID (id, method) Handler for multiple commands using a single 
| response function. Passes the menu ID in as an 
, . argument. 
EV_COMMAND_ENABLE(id, method) Enables and disables commands such as buttons 
| and menu items. 

EV_MESSAGE(message, method) General purpose macro for Windows WM_xxxx 
messages. 

EV_NOTIFY_AT_CHILD(notifyCode, method) Handles all child ID notifications at the child 

: window. 

EV_OWLDOCUMENT(id, method) _ Handles new document notifications. 

EV_OWLNOTIFY (id, method) Generic document handler. 

EV_OWLVIEW(id, method) | Handles view notifications. 

EV_REGISTERED(str, method) Handles registered MSG messages. 

EV_VIEWNOTIFY Sends a notification message from the document 
to the views. 

_ Factory template classes _ olefacto.h 


The factory template classes create éaliback code for both automated and non 
automated Doc/View and non-Doc/view ObjectWindows applications. Use these 
factory template classes to make objects for embedding and linking. (That is, when an 
application object needs to be embedded within another container, the callback function 
is responsible for creating the embedded object.) Depending on the template arguments 
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Factory template classes 


passed to the factory class, you obtain different kinds of factories designed to create the 
object you need. All the templetized classes, however, assume that the application is 
using a global AppDictionary (the application's dictionary), and a global Registrar (the 
TOcRegistrar pointer that manages registering the application in the database). 


ObjectWindows includes several factory template classes, divided into two main 
categories: those designed for Doc/View applications and those designed for non-Doc/ 
View applications. Although all these classes contain the same functions, they are 
designed to create different types of objects. 


The hierarchy chart illustrates the inheritance relationship among these classes. 


ctory Classes — ies a es eee 
TOleFactoryBase TAutoFactory 


TOleDocViewFactory TOleAutoFactory TOleDocViewAutoFactory 


. Nonvirtual inheritance 


Each class takes three arguments: the application class, the automation class, and the 
Doc/ View class. The arguments indicate whether or not the application is a Doc/View 
application and whether or not the application is automated. The factory classes and 
their definitions include the following four classes. 


Factory class for Doc/View, non-automated, OLE components 


template <class T> class TOleDocViewFactory 
: public TOleFactoryBase<T, TOleFactoryDocViewsT, 
TOleFactoryNoAuto<T>>>{}; 
Factory class for Doc/View, automated OLE components 


template <class T> class TOleDocViewAutoFactory 
: public TOleFactoryBase<T, TOleFactoryDocViewsT, 
TOleFactoryAuto<T>>>{}; 


Factory class for non-Doc/View, non-automated, OLE components 


template <class T> class TOleFactory 
: public TOleFactoryBase<T, TOleFactoryNoDocViews<T, 
TOLeFactoryNoAuto<T>>>{}; 


Factory class for non-Doc/View, automated OLE components 


template <class T> class TOleAutoFactory 
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. Factory template classes | 


= pub lac TOleFactoryBase<?, TOLeFactorytoDocViews?, 
TOleFactoryAuto<T>>>{}; 


For either a Doc/View or a non-Doc/ View application, you need to register your 
application in your OwlMain function. The argument to TOcRegistrar (in this case, 
TOleFactory<TDrawApp>) constructs an object and converts it to a TComponentFactory 
type, using the operator TComponentFactory to create a function pointer. In reality, the 
object is never created because all the factory class's functions are static. 


Pass your application object derived from TApplication as the parameter to TOleFactory, 
as the following code from STEP15.CPP illustrates: 


2 ug SE 


QwlMain(int /*argc*/, char* /*argv*/ []) 
{ 
cry 4 
Registrar = new TOcRegistrar(AppReg, TOleFactory<TDrawApp>(), 
TApplication: :GetCmdLine()); 
if (Registrar- ere neces ee aa: :AnyRegOption) ) 
return Os 

//If this is a normal exe server, run the application now; eeharniae: 
// wait until the factory is called. 

return Registrar->Run(); 


} 


In general, these are the steps each factory class follows in the default callback code: 


1 


The factory gets the application. This is the application object derived from 


TApplication. For a DLL server, there can be several instances of the object. Using 
TAppDictionary::GetA pplication, the factory verifies whether or not there is an entry in 
the application dictionary for an application object for the current process. 


If the application does not exist, the factory creates the application object and tests to 
see if the application was created successfully before creating its corresponding 
TOcApp object. If the shutdown option flag is set, it then exits. (If the application has 
already been destroyed, the shutdown flag is set.) 


If the factory is passed a shutdown option flag (one of the TOcAppMode enum 
values), it then shuts down the application and calls the factory's DestroyApp function 
to destroy the application. 


If the application is automated, the acini creates a corresponding automation 
object. 


If the object ID is not zero, the factory creates the object and gets the OLE interface. 


Otherwise, it gets the application's OLE interface. At this point, the Doc/ View and 
non-Doc/ View processes differ because they need to create different types of objects. 
If the application is automated, the factory creates an automated helper object. 


The factory checks to see if the option flag amRun (one of the TOcAppMode enum 


values) is set, and, if so, it runs the application. This occurs if the application either 


was built as an .EXE or is a DLL running as an .EXE. If the amRun flag is not set and 
the application is an in-proc DLL server and.should not be running, the factory just 
starts the application. 
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Factory template classes 


7 The factory returns either the OLE interface for the object or 0 if no interface was 
requested or if an error occurred. 


The following diagram illustrates this process. 


Get Application 


Does the 
Application 
ist? 
=" : Shutdown 
Application 
? 


Destroy Application 


Shutdown ¥ N: 

Application : 

? : 

N i 
Call Create 

Application | 


Was the 


Application 
created? 


Y 
Create OC 
Application 
Automate 


the 
Application? 


Create automated 
Application 
| 
Get the Application’s |_ N Tse 
OLE interface 
<>0? 


| | 
N Run the 
Application 
Return the | 
OLE interface 


The factory can be called back to walk through this process several times: 


1 On the first callback, the factory creates the application, and if the amRun flag is set, it 
enters a message loop. | | 
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GetApplicationObject function | 


2 On the second callback, OLE calls the aeionyt fo automate or embed or link an object. 
In the case of an embedded and/or linked object, this pass can occur one or more 
times. (In the case of an automation object, however, this second pass occurs only 
once because any subsequent requests pass through the automated ace itself.) 


3 On the ee callback, the factory shuts down the application. 


See also 

TAutoFactory class, TAutoFactory::DestroyApp, oe ee aoe 
TOcAppMode enum, TOcRegistrar class, TOleFactoryBase class, — 
TOleFactoryBase: rome TOleFactoryBase: :TComponentFactory 


TApplication* GetApplicationObject(unsigned pid = 0); | 
This global function is included mainly for backward compatibility with previous 
ObjectWindows applications. To find the application object associated with a process 
ID, GetApplicationObject calls TAppDictionary::GetApplication on an application 
dictionary. Used by EXEs or DLLs statically linking ObjectWindows, 
_GetApplicationObject can return 0. 


Seealso GetWindowPtr function, TAppDictionary: Caroler 


GetWindowPtr function | ~ window.h 


TWindow* GetWindowPtr(HWND hWnd); 

This global function is included mainly for backward compatibility with previous 
ObjectWindows applications. First, GetWindowPtr calls the global function 
GetApplicationObject to find the application. Then, calls TApplication's GetWindowPtr to 
get the [Window pointer associated with the window. 


See also GetApplicationObject function, TApplication::GetWindowPtr 


ID_xxxx file constants inputdia.rh 


Resource and control IDs for the input dialog box. 


ID_INPUT Control ID for the user input 
ID_PROMPT Control ID for the static text 


Seealso TInputDialog::SetUpWindow — 
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ID_xxxx printer constants 


ID_xxxx printer constants printer.rh 


Resource and control IDs for the printer abort dialog box. 


Constant - ee : : | Meaning — Soles 
IDD_ABORTDIALOG Resource ID number for the abort + dialog box. 
ID_TITLE Control ID for the selected printer driver. 
ID_DEVICE Control ID for the selected printer. 
ID_PAGE ID number for the page number text control. 
ID_PORT Control ID for the selected printer port. 
IDA_xxxx accelerator ID constants editfile.rh 


Resource ID for accelerator keys. 


Constant = a . _ Meaning — . 
IDA_ EDITHILE _ Resource ID es accelerator keys. 
IDA_xxxx OLE accelerator ID constants oleview.rh 


Resource ID for accelerator keys. 


| IDA_OLEVIEW Resource ID for accelerator keys for OLE enabled applications. 


IDM_xxxx menu ID constants editfile.rh 


Resource ID for menu selections. 


‘IDM_EDITFILE Resource ID for menu selections. 


Menu IDs for OLE-enabled applications. 


IDM_OLEPOPUP OLE enabled application pop-up menu 
IDM_OLEVIEW OLE enable application view menu selection 
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- 1DS_xxxx edit view ID constants 
IDS xx edit view ID constants oleview.rh 


String constants used to respond to edit view commands. 


Es JE 
IDS_EDITCONVERT 
IDS_EXITSERVER 


it the object 
Convert the object 
Exit the server application 


IDS Mode constants statusba.th 


Resource and command IDs to use with TStatusBar. 


IDS_MODES 
-IDS_MODESOFF 


IDS_x0x document string ID constants 


String resource to define mode On indicators 
String resource to define mode Off indicators 


siete rh 


String IDs that define resource IDs used to determine the status of the document. 


IDS_DOCCHANGED 


IDS_DOCLIST 
IDS_DOCMANAGERFILE 
IDS_DUPLICATEDOC 
IDS_NODOCMANAGER 
IDS_NOMEMORYFORVIEW 
IDS NOTCHANGED _ 
IDS_READERROR 
TDS_UNTITLED 
IDS_UNABLECLOSE 
IDS_UNABLEOPEN 
IDS_UNTITLED 
IDS_VIEWLIST 
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If the document has been changed, displays the message, "Do you 
want to save the changes?" 


Document is a document type. 

This is a document manager file. 

This is a duplicate document. 

There is no document manager. 

Not enough memory to view the document 

The document has not been changed. 

Error while reading the file 

The file is untitled. 

Document manager is unable to close the document. 


‘Document manager is unable to open the document. 


Document is untitled. 


Document is a view type. 


IDS_xxxx edit file ID constants 


IDS_xxxx edit file ID constants 


editfile.rh 


string constants used by edit and file classes to display information about files. 


Constant 
IDS_FILECHANGED 


The text in the file has changed. Do you want to save 


the changes? 


IDS_FILEFILTER 
IDS_UNABLEREAD 
IDS_UNABLEWRITE 


IDS_UNTITLEDFILE 
edited. 


IDS_xxxx exception message constants 


Use this filter to display text files. 

Unable to read the file from the disk. 

Unable to write the file to the disk. 

The default window title unless the file is being 


General and application exception message constants. The following list groups the 
constants according to message type: 


IDS_INVALIDMAINWINDOW 
IDS_INVALIDMODULE 
IDS_NOAPP 
IDS_OKTORESUME 
IDS_OWLEXCEPTION 
IDS_OUTOFMEMORY 
IDS_UNHANDLEDXMSG 
IDS_UNKNOWNERROR 
IDS_UNKNOWNEXCEPTION 
Owl 1 compatibility messages: 
IDS_INVALIDCHILDWINDOW 
IDS_INVALIDCLIENTWINDOW 
IDS_INVALIDWINDOW 
TXWindow messages: 
IDS_CHILDCREATEPAIL 
IDS_CHILDREGISTERFAIL 
IDS_CLASSREGISTERFAIL 
IDS_LAYOUTCOMPLETE 
IDS_LAYOUTBADRELWIN 
IDS_MENUFAILURE 
IDS_PRINTERERROR 
IDS_VALIDATORSYNTAX 
IDS_WINDOWCREATEPFAIL 
IDS_WINDOWEXECUTEFAIL 


Invalid MainWindow 
Invalid module specified for window 


No application object 
Resume in spite of error 
Unknown exception 
Out of memory 
Unhandled xmsg error 
Unknown error 


Unknown exception error 


Invalid child window 
Invalid client window 
Invalid window 


Child create fail for window 

Child class registration fails for window 
Class registration fails for window 
Layout window failure 

Layout window failure 

Menu creation failure 

Printer error | 

Validator syntax error 

Create fail for window 

Execute fail for window 
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IDS_xxxx listview ID constants 


messages: 
IDS GDIALLOCFAIL GDI allocate failure 
IDS_GDICREATEFAIL GDI creation failure 
IDS_GDIDELETEFAIL : GDI object delete failure 
IDS_GDIDESTROYFAIL GDI object destroy failure 
IDS_GDIFAILURE ? GDI failure | 
IDS_GDIFILEREADFAIL | GDI file read failure 
_ IDS_INVALIDDIBHANDLE Invalid DIB handle 
IDS . GDIRESLOADFAIL | GDI resource load failure 
IDS_00x listview ID constants listview.rh 


Define operations performed on views. These include clearing the document, inserting a 
new line, copying text to the Clipboard, and so on. 


IDS_LISTVIEW | ‘Resource ID for listview constants. 


Constants used by printer classes to determine the printer status. 


_ IDS_PRNCANCEL Printing is canceled. 

~ IDS_PRNERRORCAPTION Printer error occurred. 
IDS_PRNERRORTEMPLATE Document was not printed. 
TIDS_PRNGENERROR Error encountered during printing. 
IDS_PRNMGRABORT Printing aborted in Print Manager. 
IDS_PRNON Printer is on. 
IDS_PRNOUTOFDISK Out of disk space. 
IDS_PRNOUTOFMEMORY = ~—_ Out of memory. 

IDS_xxxx validator ID constants et validate.rh 


Defines several constants used by validator classes to determine the validator status. 


IDS_VALPXPCONFORM _ Item doesn't conform to correct picture format. 
IDS_VALINVALIDCHAR Character isn't one of the valid entries. 
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IDW_MDICLIENT constant 


oe Meaning vce 
IDS VALNOTINRANGE Entry isn't within the sediied range. 
IDS_VALNOTINLIS String isn't found in the list of valid entries. 


IDW_MDICLIENT constant 


IDW_MDICLIENT 
Child ID constant used to identify MDI client windows. 


IDW_MDIFIRSTCHILD constant 


IDW_FIRSTMDICHILD 


Child ID constant used to identify the first MDI client window. 


LangXxxx ID constants 


framewin.h 


framewin.h 


locale.h 


A language ID is 16-bit number representing a language. In a ea a 


language ID is a value of type TLaneld. 


A language ID is composed of two parts. The ten low-order bits identify a language and 
the six high-order bits identify a dialect or sub-language. For example,alanguageID _ 
can specify simply French, or make use of the upper bits to designate Belgian French, 


Swiss French, or Canadian French. 


ObjectComponents defines constants to represent three common IDs: 


LangSysDefault The default language set for the system. i. 


LangUserDefault The default language set for a particular user (which can differ from the system 


setting on multi-user systems.) 


LangNeutral A neutral setting signifying no particular locale. An application that receives this 


value uses its own default setting. 


Seealso TLangld typedef, TLocaleString 


LBN_ xxxx list box message constant 


Indicate changes in the status of the list box. 


LBN_DBLCLK Mensnere when the user pious a string | in a list box 
LBN_ERRSPACE Message sent when the list box is out of memory 
LBN_KILLFOCUS Message sent when the list box is losing the input focus 


windows.h 
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ImParent constant 


LBN_SELCANCEL Message sent when the user cancels the selection in a list box 
LBN_SELCHANGE Message sent when the user changes the selection in a list box 
LBN_SETFOCUS Message sent when the list box receives the input focus. — 


ImParent constant layoutco.h 


#define ImParent 0 
LmParent is used to construct layout metrics (for example, edge and size constraints). 


Seealso TLayoutConstraint struct 


long LongMulDiv(long mul, long mul2, long div1); 

TScroller uses this function to convert horizontal range values (XRange) from the scroll 
bar to horizontal scroll values (XScrollValue) and vice versa, or to convert vertical range 
values (Y Range) from the scroll bar to vertical scroll values (YScroll Value) and vice versa. 


Seealso TScroller 


const int MAX_RSRC_ERROR_STRING = 255; 
Maximum number of characters possible for an error message. 


MB_Xxxx message constants - _windows.h 


Contain information about the style and behavior of a message dialog box. You can use 
these constants to determine the kinds of information displayed in a message dialog 
box. 


MB_OK The message dialog box contains an OK push button. 
MB_OKCANCEL | The message dialog box contains Cancel and OK push buttons. | 
MB_ABORTRETRYIGNORE _ The message dialog box contains Abort, Retry, and Ignore push buttons. 
MB_YESNOCANCEL The message dialog box contains Yes, No and Cancel push buttons. 
MB_YESNO The message dialog box contains Yes and No push buttons. 
-MB_RETRYCANCEL The message dialog box contains Retry and Cancel push buttons. 
MB_ICONHAND The message dialog box contains a stop sign icon. 
MB_ICONQUESTION The message dialog box contains a question mark. — 


MB_ICONEXCLAMATION The message dialog box contains an exclamation mark. 
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Constant 
MB_ICONASTERISK 
MB_ICONINFORMATION 
MB_ICONSTOP 
MB_ICONHAND 
MB_DEFBUTTON1 


MB_DEFBUTTON2 
MB_DEFBUTTON3 
MB_APPLMODAL 


MB_SYSTEMMODAL 


MB_TASKMODAL 


NBits function 


The message dialog box contains an icon consisting of a lowercase letter i. 
The message dialog box contains an icon consisting of a lowercase letter i. 
The message dialog box contains a stop sign icon. 
The message dialog box contains a stop-sign icon. 


The first button is the default button in the message dialog box. This is 
always the case unless MB_DEFBUTTON2 or MB_DEFBUTTONS is 
specified. 


The second button is the default button in the message dialog box. 
The third button is the default button in the message dialog box. 


Before continuing to work in this window, the user must answer the 
message dialog box. However, the user can work in other windows. 
MB_APPLMODAL is the default unless MB SYSTEMMODAL, 
MB_TASKMODAL, or MB_-NOFOCUS is specified. 


Before continuing to work in this window, the user must answer the 
message dialog box. Unless the application indicates MB_ICONHAND, 
the message box does not become modal until after it is created. The 
owning window and other windows can continue to receive messages. 
You can use MB_SYSTEMMODAL to notify the user of serious errors, 
such as lack of sufficient memory to run an application, that must be 
taken care of immediately. 


Before continuing to work in this window, the user must answer the 
message dialog box. However, the user can work in other windows. 
Unlike MB_APPLMODAL, all top-level windows in the current task are 
disabled. Use this constant when the calling application does not have a 
window handle available, and you want to prevent input to other 
windows in the current application without actually preventing the other 
applications from executing. 


Seealso §TDocument::PostError, TDocManager::PostDocError, TWindow::MessageBox 


NBits function 


uint16 NBits(long colors); 


color.h 


Returns the bit count corresponding to the given color count. 


See also NColors, TColor class 


NColors function 


int NColors(uint16 bitCount); 


color.h 


Returns the color count corresponding to the given bit count, or —1 if the bit count is not 
supported by Windows. Bit counts currently supported are 1, 4, 8, and 24. 


Seealso NBits, TColor class 


Chapter 2, ObjectWindows library reference 47 


OFXXXX a cums open enum 


OOO document open enum docview.h 


Defines the document and open sharing modes used for constructing streams and 
storing data. Any constants that have the same functionality as those used by OLE 2.0 
docfiles are indicated in the following table; for example, STGM_TRANSACTED, 
STGM_CONVERT, STGM_PRIORITY, and STGM_DELETEONRELEASE. | 


_ Although files are typically used for data storage, databases or spreadsheets can also be 
used. I/O streams rather than DOS use these bit values. Documents open the object 
used for storage in one of the following modes: | 


ofParent storage object is opened using the parent's mode. 
ofRead A storage object is opened for reading. 
ofWrite A storage object is opened for writing. 
ofReadWrite A storage object is opened for reading and writing. 
ofAtEnd Seek to end-of-file when opened originally. _ 
ofAppend Data is appended to the end of the storage object. 
ofTruncate An already existing file is truncated. | 
ofNoCreate Open fails if file doesn't exist. 
ofNoReplace Open fails if file already exists. 
ofBinary Data is stored in a binary, not text, format. Carriage returns are not stripped. 
oflosMask All of the above bits are used by the ios class. 
ofTransacted Changes to the storage object are preserved until the data is either committed to 
permanent storage or discarded. (STGM_TRANSACTED) 
ofPreserve Backs up previous storage data using before creating a new storage object with 
| the same name. (STGM_CONVERT) 
ofPriority Supports temporary, efficient reading before opening the storage. 
: 7 (STGM_PRIORITY) 
ofTemporary The storage or stream is automatically destroyed when it is destructed. 


(STGM_ DELETEONRELEASE) 


Seealso TStream, TInStream, TOutStream 


docview.h | 


pfxxxx property attribute constants — 


Define document and view property attributes. Documents, views, and applications use 
these attributes to determine how to process a document or view. 


P! 7 perty 

pfGetBinary _ Property is accessible as a native nontext format. 
pfConstant _ Property can't be changed for the object instance. 
pfSettable Property can be set as a native format. 
pfUnknown Property is defined but unavailable for the object. 
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_BUILDOWLDLL macro 


pfHidden eae aipuid bs hidden eon ie user pdarne re nontal inane 
pfUserDef Property has been user-defined at run time. 


Seealso Document, TView 


_BUILDOWLDLL 

Used internally to control values for the OWLCLASS, OWLDATA, and OWLFUNC 
macros. This macro is defined when the user's module is built as a DLL. It must be 
defined and included in ObjectWindows makefiles to build the ObjectWindows DLL. 


Seealso ~OWLDLL macro 


_QWLCLASS macro owldefs.h 


_OWLCLASS 
Used internally by ObjectWindows to modify an entire class for use in a DLL. It is the 
ObjectWindows version of _RTLCLASS adjusted to export and import WIN32 DLLs. 


For static WIN16 and WIN32 , the default models are used. When ObjectWindows is 
being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 
DLLs, this macro evaluates to _import and performs necessary operations for WIN32 
DLLs. For WIN16 DLL use, this macro evaluates to _import, which is essentially the 
same as _huge. 


OWLDATA macro owldefs.h 


_OWLDATA 
The ObjectWindows version of _RTLDATA adjusted to export and import WIN32 DLLs 
for ObjectWindows. OWLDATA modifies a specific data declaration. 


For static WIN16 and WIN32, the default models are used. When ObjectWindows is 
being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 
DLLs, this macro evaluates to _import and performs necessary operations for WIN32 
DLLs. For WIN16 DLLs, this macro evaluates to nothing. 


~QWLDLL macro | owldefs.h 


_OWLDLL | 

_OWLDLL, which is automatically defined if _RTLDLL is turned on, controls values for 
the OWLCLASS, OWLDATA, and OWLFUNC macros. It is also automatically 
defined if the user_OWLDLL module is used as a DLL from another user module. It 
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_OWLFAR macro 


must be defined if you are writing ObjectWindows applications o or DLLs that use DLLs. 
This macro can also be turned on by a makefile. : 


“OWLFAR m macro | | | owldefs.h 


_OWLFAR 


The macro _OWLFAR is the ObjectWindows version of _RTLFAR adapted to promote 
far data pointers in DLLs for ObjectWindows. 


_OWLFARVTABLE macro : willie 


_OWLFARVTABLE 


Moves the ObjectWindows virtual function tables (vtables) out of the DGROUP of the 
data segment and stores them in the code segment. Use this macro in conjunction with 
the COOWLCLASS macro to add the _huge option when static models are compiled. 


_OWLFASTTHIS macro owldefs.h 
“OWLFASTTHIS 


The macro _OWLFASTTHIS causes _fastthis to be added to the OWLCLASS macro so 
that all ObjectWindows classes use the fastthis calling convention for passing the this _ 
parameter in the registers. This macro, which has the same effect as using the —po 
compiler option, applies to 16-bit code only. 


_OWLFUNC macro owldefs.h 
_OWLFUNC 


The ObjectWindows function version of _RTLFUNC adapted to export and import 
functions for building WIN32 DLLs for ObjectWindows. OWLFUNC modifies a 
specific member or global function for use in a DLL. 


For static WIN16 and WIN32 DLLs, the default models are used. When ObjectWindows 
is being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 
DLLs, this macro evaluates to _import and performs necessary operations for WIN32 
DLLs. For WIN16 DLL use, this macro evaluates to nothing. 


OWLGetVersion function =n. 


unsigned short far_OWLFUNC OWLGetVersion(); 
Returns the version number of the ObjectWindows library. The version number is 
Represented as an in unsigned short. 
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SB Xxxx scroll bar constants 


SB_Xxxx scroll bar constants windows.h 
The following constants define scroll bar modes: 
Const : Meaning a ee : | 
SB_BOTH Displays or hides the Honzontsl and vertical scroll bars for a ee 
SB_CTL Displays or hides a scroll bar's control button. 
SB_HORIZ Displays or hides the horizontal scroll bars for a window. 
SB_VERT Displays or hides the vertical scroll bar for a window. 
shxxxx document sharing enum docview.h 


The following file-sharing modes are available when opening document streams. 


es Meaning — Di Pe rr 
Used for sreciacaerie nan erienis but should be avoided if if possible. 
DENY_ALL functionality. 

DENY_WRITE functionality. 


shWrite | DENY_READ functionality. 
shReadWrite DENY_NONE functionality 
shDefault Use stream implementation default value. 
shMask Mask for file-sharing bits. 
TActionFunc typedef window.h 


typedef void(*TActionFunc)(TWindow* win, void* param); 
Passes a function pointer to TWindow::ForEach. 


See also TWindow::ForEach 


VActionMemFunc typedef window. 


typedef void(TWindow::*T ActionMemFunc)(TWindow* win, void* param); 
Passes a member function pointer to TWindow::ForEach. 


See also TWindow::ForEach 


typedef void(GENERIC::*TAnyPMF)(); 
A generic pointer to a member function. 
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_ TAnyDispatcher ios adatr. 


typedef LRESULT(*TAnyDispatcher)(GENERIC&, TAnyPMF, WPARAM, LPARAM): 
A message dispatcher type. All message ar functions conform to this type and 
take four parameters: 


e A reference to an object 


e A pointer to the member function in which the signature varies according to the 
cracking that the function performs : 


¢ WPARAM 
¢ LPARAM | 


TAppDictionary class appticth 


A TAppDictionary is a dictionary of associations between a process ID and an 
application. A process ID identifies a process, that is, a program (including all of its 
affiliated code, data, and system resources) that is loaded into memory and ready to 
execute. A TAppDictionary supports global application lookups using the global 
GetApplicationObject function or TAppDictionary's GetApplication function. If you do not 
define an application dictionary, ObjectWindows provides a default, global application 
dictionary that is exported. In fact, for EXEs, this global application escuonatyd is 
automatically used. 


TAppDictionary includes a TEntry struct, which stores the process ID and the 
corresponding application associated with the ID. The public member functions add, 
find, and remove the entries in the appplication dictionary. | 


If you are statically linking ObjectWindows, you do not have to explicitly create an 
application dictionary because the default global ObjectWindows application dictionary 
is used. However, when writing a DLL component that is using ObjectWindows in a 
DLL, you do need to create your own dictionary. To make it easier to define an 
application dictionary, ObjectWindows includes a macro 
DEFINE_APP_DICTIONARY, which automatically creates or references the correct 
dictionary for your application. 


Although this class is transparent to most users building EXEs, component DLLs need 
to create an instance of a TApplication class for each task that they service. This kind of 
application differs from an EXE application in that it never runs a message loop. (All the 
other application services are available, however.) 


Although a component may consist of several DLLs, each with its own TModule, the 
component has only one TApplication for each task. A TAppDictionary, which is used for 
all servers (including DLL servers) and components, lets users produce a complete, self- 
contained application or component. By using a ae gen these components can 
share application objects. 


When 16-bit ObjectWindows is statically linked with an EXE or under Win32, with per- 
instance data, the TAppDictionary class is implemented as a wrapper to a single 
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TAppDictionary class 


application pointer. In this case, there is only one TApplication that the component ever 
sees. 


To build a component DLL using the ObjectWindows DLL, a new TAppDictionary object 
must be constructed for that DLL. These are the steps an application must follow in 
order to associate the component DLL with the TAppDictionary, the application, and the 
window class hierarchy: 


1 Use the DEFINE_APP_DICTIONARY macro to construct an instance of 
TAppDictionary. Typically, this will be a static global in one of the application's 
modules (referred to as "AppDictionary"). The DEFINE_DICTIONARY macro allows 
the same code to be used for EXEs and DLLs. 


TAppDictionary AppDictionary; 


2 Construct a generic TModule and assign it to the global ::Module. This is the default 
provided in the ObjectWindows' LibMain function. 


LibMain(...) 
::Module = new TModule(0, hInstance) ; 
3 When each TApplication instance is constructed, pass a pointer to the TAppDictionary 
as the last argument. This ensures that the application will insert itself into this 
dictionary. In addition, for 16 bit DLLs, the gModule argument needs to be supplied 


with a placeholder value because the Module construction has already been 
completed at this point, as a result of the process performed in step 2. 


TApplication* app = new TMyApp(..., app, AppDictionary); 


4 Ifthe Doc/View model is used, supply the application pointer when constructing the 
TDocManager object. 


SetDocManager (new TDocManager (mode, this)); 


5 When a non-parented window (for example, the main WHat) is being constructed, 
pass the application as the module. | 


SetMainWindow(new TFrameWindow(0, "", false, this)); 


See also 
TApplication::GetWindowPtr, TWindow::GetWindowPtr, 
DEFINE _APP DICTIONARY macro 


Type definitions 


TEntry 

struct TEntry { 

unsigned Pid; 

TApplication* App; 

} 

An application dictionary entry that associates a process ID (Pid) with an application 
(App). The dictionary is indexed by (Pid) and can have only 1 entry per process ID. 


Seealso TAppDictionary::TEntry struct, TAppDictionary::Iterate 
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TEntrylterator 

typedef void(*TEntrylterator) (TEntry&); : 

A dictionary iterator function pointer type that receives a reference to an entry. You can 
supply a function of this type to the Iterate function to iterate through the entries in the 
dictionary. 


Seealso TAppDictionary::TEntrylterator typedef — 


Public constructor and destructor 


Constructor 
TAppDictionary(); 
Constructs a TAppDictionary object. 


Destructor 

~TAppDictionary(); 

Destroys the TAppDictionary object and calls DeleteCondemned to clean up the 
condemned applications. 


Public member functions 


Add 

~ void Add(TApplication* app, unsigned pid = 0); 
Adds an application object (app) and corresponding process ID to this dictionary. The 
default ID is the current process's ID. | 


See also. TAppDictionary::Remove 


Condemn 

void Condemn(TApplication* app); 

Marks an application in this dictionary as condemned by z zeroing its process ID so that 
the application can be deleted later when DeleteCondemned is called. 


See also TAppDictionary: ‘DeleteCondemned — 


DeleteCondemned 

bool DeleteCondemned(); 

Deletes all condemned applications and their associated process IDs from the 
dictionary. If no applications remain in the dictionary, DeleteCondemned returns true. 


Seealso TAppDictionary::Condemn 


GetApplication 

TApplication* GetApplication(unsigned pid = 0); 

Looks up and returns the application associated with a given process ID. The default ID 
is the ID of the current process. If no application is associated with the process ID, 
GetApplication returns 0. 


Iterate 
void Iterate(TEntrylterator iter); 
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Iterates through a list of entries in the application dictionary, calling the iter callback 
function for each entry. 


Seealso TAppDictionary::TEntrylterator 


Remove 

Form 1 void Remove(TApplication* app); 
Searches for the dictionary entry using the specified application (app). Then, removes a 
given application and process ID entry from this dictionary, but does not delete the 
application. 


Form 2 void Remove(unsigned pid); 
Searches for the dictionary entry using the specified process ID (pid). Then, removes a 
given application and its associated process ID entry from this dictionary, but does not 
delete the application. 


Seealso TAppDictionary::Add 


Derived from TModule, TApplication acts as an object-oriented stand-in for an 
application module. TApplication and TModule supply the basic behavior required of an 
application. [Application member functions create instances of a class, create main 
windows, and process messages. 


Public data members 


HAccTable 

HACCEL HAccTable; | 

Included to provide backward compatibility, HAccTable holds a handle to the current 
accelerator table being used by the application. New applications should instead use the 
accelerator table handle TWindowAttr::AccelTable for each window object in the 
application. 


Seealso TWindow::LoadAcceleratorTable, TWindowAttr struct 


hPrevinstance 

HINSTANCE hPrevinstance; 

Contains the handle of the previously executing instance of the Windows application. If 
hPrevInstance is 0, there was no previously executing instance when this instance began 
execution. Under Win32, this value is always 0. 


nCmdShow 
int nCmdShow; 
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Form 1 


Indicates how the main window is tobe displayed (either maximized or as an icon). 
These correspond to the WinMain parameter nCmdShow. nCmdShow can contain one of 
the following constants: | | 7 


SW_HIDE — 7 Hides the window. 


SW_MINIMIZE Minimizes the specified window. 
SW_SHOW Activates a window using current size and position. 


SW_SHOWMAXIMIZED _ Displays a maximized window. 
SW_SHOWMINIMIZED Displays a minimized window. 


SW_SHOWNA Displays window in its current state. 
SW_SHOWNOACTIVATE ___ Displays the window as an icon. 
SW_SHOWNORMAL Displays a window in its original size and spain: | 
SW_SHOWSMOOTH Shows a window by updating it in a bitmap and then copying the bits to 
the screen. 
Type definitions 
XS 


enum {xsUnknown, xsBadCast, xsBadTypeid, xsMsg, xsAlloc, xsOwl}; 

These bit flags define the types of exceptions that are caught and suspended. 
TApplication: ae and TApplication::QueryThrow return the values of these bit 
flags. | 


The following table shows the xs exception enum constants: 


xsUnknown Unknown exception 
_xsBadCast Bad_cast exception 
xsBadTypeid Bad_typeid exception 
xsMsg Any exception derived from xmsg 
xsAlloc xalloc exception 
xsOwl TXOuwl exception 


Seealso TXOwl, TApplication::QueryThrow, TApplication::SuspendThrow 


Public constructor and destructor 


Constructor 

TApplication(const char far* name = 0, TModule*& gModule = ::Module, TAppDictionary* appDict = 0); 

This TApplication constructor creates a new T Application object named name. You can use 
gModule to specify the global module pointer that points to this application. The appDict 
parameter specifies which dictionary this application will insert itself into. To override 
the default ObjectWindows TAppDictionary dee pass a jaa to a user-supplied 


| appre object. 


56 ObjectWindows Reference Guide 


Form 2 


TApplication class 


TApplication(const char far* name, HINSTANCE hinstance, HINSTANCE hPrevinstance, 

const char far* cmdLine, int cmdShow, TModule*& gModule = ::Module, TAppDictionary* appDict = 0); 
This TApplication constructor creates a TApplication object with the application name 
(name), the application instance handle (instance), the previous application instance 
handle (prevInstance), the command line invoked (cmdLine), and the main window show 
flag (cmdShow). The appDict parameter specifies which dictionary this application will 
insert itself into. To override the default ObjectWindows TAppDictionary object, pass a 
pointer to a user-supplied appDict object. 


If you want to create your own WinMain, use this constructor because it provides access 
to the various arguments provided by WinMain. You can use gModule to specify the 
global module pointer that points to this application. 


Destructor 
~TApplication(); 
~TApplication destroys the TApplication object. 


See also TApplication::nCmdShow, TModule, TAppDictionary 


Public member functions 


BeginModal 

int BeginModal(TWindow* window, int flags = MB_APPLMODAL); 

BeginModal is called to begin a modal window's modal message loop. After determining 
which window to disable, saves the current status of the window, disables the window, 
calls MessageLoop, and then reenables the window when the message loop is finished. 
The flags determine how BeginModal treats the window. flags can be one of the following 
values: | 


“MB_APPLMODAL 


e window to be disabled (which is usually an ancestor of the moda 
is identified by window. If window is 0, no window is disabled. 


MB_SYSTEMMODAL _ The window to become system modal is identified by window. 


MB_TASKMODAL All top-level windows are disabled, and window is ignored. BeginModal returns 
—1 if an error occurs. 


window) 


See also TWindow 


BWCCEnabled 

bool BWCCEnabled(); 

Indicates if the Borland Custom Controls library (BWCC) is enabled. Returns true if 
BWCC is enabled and false if BWCC is disabled. 


CanClose 

virtual bool CanClose(); 

Returns true if it's OK for the application to close. By default, CanClose calls the CanClose 
member function of its main window and returns true if both the main window and the 
document manager (TDocManager) can be closed. If any of the CanClose functions return 
false, the application doesn't close. | | 
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This member function is seldom redefined; acing behaviors is usually sedicaneda in the 
main window's CanClose member function, if needed. 


Seealso TWindow::CanClose, TDocManager 


Condemn 
void Condemn(TWindow* win); 
Performs window cleanup. 


Ctl3dEnabled 

bool Ctl3dEnabled() const; 

Returns true if the Microsoft 3-D Controls Library DLL is enabled. This DLL gives 
controls a three-dimensional look and feel. 


Seealso TApplication::EnableCtl3d, TApplication:FnableCii3dAutosubclass 


EnableBWCC 

void EnableBWCC(bool enable = true, uint Language = 0); 

Loads and registers BWCC.DLL if you are running 16-bit applications or BWCC32.DLL 
_ if you are running 32-bit applications. By default, BWCC is enabled. To disable BWCC, 

set enable to false. 


Seealso TDialog 


EnableCti3d 

void EnableCtl3d(bool enable = true); 

Enables or disables the use of the CTL3D DLL. If enable is true, EnableCtl3d loads and 
registers the CTL3D.DLL if it's not already enabled. 


See also TApplication::Ctl3dEnabled, TApplication::EnableCtl3dAutosubclass 


EnableCtl3dAutosubclass 

void EnableCtl3dAutosubclass(bool enable); 

Enables or disables CTL3D's use of autosubclassing if CTL3D is already enabled using 
Ctl3dEnabled. If autosubclassing is enabled, any non-ObjectWindows dialog boxes have 
a 3-D effect. The common dialog classes and TDocManager use this function to turn on 
autosubclassing before creating a non-ObjectWindows dialog box to make it three- 
dimensional and to turn off ak re, after the dialog box is 
destroyed. 


Seealso TDialog::EvCtlColor, TApplication: EnableCtl3d, TApplication: Ct13dEnabled 


EndModal 
void EndModal(int result); 

_EndModal is called to end a modal window's modal message loop. Sets result to —-1 if an 
error occurs. 7 


Find 

bool Find(TEventinfo &, TEqualOperator = 0); 

Because T’Application has no event table itself, it defers event handling to the 
DocManager. If a DocManager has been installed, Find calls TDocManager to handle 
events. 


See also TEventHandler::TEventInfo 
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GetBWCCModule 
TModule* GetBWCCModule() const; 
Returns a pointer to the enabled BWCC module. 


GetCtl3dModule 
TModule* GetCtl3dModule() const; 
Returns a pointer to the enabled Ctl3d module. 


GetDocManager 
TDocManager* GetDocManager(); | 
Returns a pointer to the document manager object that invoked the application. 


See also TApplication::SetDocManager, TDocManager 


GetMainWindow 
TFrameWindow* GetMainWindow(); 
Returns a pointer to the application's main window. 


Seealso ‘TApplication::SetMainWindow, TFrameWindow 


GetWindowPtr 

TWindow* GetWindowPtr(HWND hWnd) const; 

Retrieves a TWindow pointer associated with the handle to a window (hWnd). Allows 
more than one application to share the same HWND. | 


See also —TWindow::GetWindowPtr 


GetWinMainParams 

void GetWinMainParams(); 

Initializes a static instance of an application. ObjectWindows OwlMain uses this function 
to support static application instances. 


Seealso TApplication::SetWinMainParams 


MessageLoop 

virtual int MessageLoop(); | 

Operates the application's message loop, which runs during the lifetime of the 
application. Queries for messages; if one is received, MessageLoop processes it by calling 
ProcessAppMsg. If the query returns without a message, MessageLoop calls IdleAction to 
perform some processing during the idle time. MessageLoop calls PumpWaitingMessages 
to get and dispatch waiting messages. MessageLoop can be broken if BreakMessageLoop is 
set by EndModal. 


Seealso TApplication::BreakMessageLoop, TApplication::IdleAction, 
TApplication::ProcessAppMsg, TApplication::Pump Waiting Messages 


PostDispatchAction 

void PostDispatchAction(); 

If TApplication’s message loop is not used, this function should be called after each 
message is dispatched | 


PreProcessMenu 
virtual void PreProcessMenu(HMENU hmenu); 
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| Your application can call PreProcessMenu to process the main window s menu before it 
is displayed. 7 


‘See also shi siepaiaatiaiiaamede TMenu::TMenu 


ProcessAppMsg 

virtual bool ProcessAppMsg(MSG& msg); 

Checks for any special processing that is required for modeless dialog box, accelerator, 
and MDI accelerator messages. Calls the virtual TWindow::PreProcessMsg function of the 
window receiving the message. If your application does not create modeless dialog 
boxes, does not respond to accelerators, and is not an MDI application, you can improve 
performance by overriding this member function to return false. 


Seealso 9TWindow::PreProcessMsg, MSG struct 


PumpWaitingMessages 

bool PumpWaitingMessages(); 

Called by MessageLoop, PumpWaitingMessages processes and dispatches all waiting 
messages until the queue is empty. It also sets BreakMessageLoop when a WM_QUIT 
message is received. 


See also Application: ‘MessageLoop, TApplication: BreakMessageL.oop 


QueryThrow 

int QueryThrow(); 

QueryThrow tests to see if an exception is suspended and returns one or more of the bit 
flags in the xs exception status enum. 7 


See also xs exception status enum 


ResumeThrow 

void ResumeThrow(); 

ResumeThrow checks and rethrows suspended exceptions. Call this function any time 
you reenter ObjectWindows code from exception-unsafe code where an exception could 
have been thrown. 


Run 

virtual int Run(); 

Initializes the instance, salle InitApplication for the first executing instance and 
InitInstance for all instances. If the initialization is successful, Run calls MessageLoop and 
runs the application. If exceptions are thrown outside the message loop, Run catches 
these exceptions. 


If an error occurs in the creation of a window, Run throws a TXWindow exception. If 
Status is assigned a nonzero value (which ObjectWindows uses to identify an error), a 
-TXCompatibility exception is thrown. 


See also TApplication::InitApplication, TApplication::InitInstance, 
_ TApplication::MessageLoop, POON, a aaa 


SetWinMainParams 
static void SetWinMainParams(HINSTANCE hinstance, HINSTANCE hPrevinstance, const char far* cmdLine, 
int cmdShow); | 
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Form 2 


Form 3 


Form 4 


TApplication class 


ObjectWindows default WinMain function calls SetMainWinParams so that TApplication 
can store the parameters for future use. To construct an application instance, WinMain 
calls the OwlMain function that's in the user's code. As it's being constructed, the 
application instance can fill in the parameters using those set earlier by 
SetMainWinParams. 


Seealso TApplication::;GetWinMainParams 


SuspendThrow 
void SuspendThrow(xalloc& x); 
This version of SuspendThrow saves xalloc exception information. 


void SuspendThrow(xmsg& x); 
This version of SuspendThrow saves xmsg exception information. 


void SuspendThrow(TXOwl& x); 
This version of SuspendThrow saves a copy of a TXOwl exception. 


void SuspendThrow(int); 
This version of SuspendThrow sets the xs exception status bit flags to the specified 
exception, for example Bad_cast or Bad_typeid. 


Seealso xs exception status enum, TXOwl 


Uncondemn 
void Uncondemn (TWindow* win); 
Removes condemned children from the list of condemned windows. 


Seealso TWindow 


Protected data members 


BreakMessageLoop 

bool BreakMessageLoop; 

Causes the current modal message loop to break and terminate. If the current modal. 
message loop is the main application, and your program sets BreakMessageLoop, your 
main application terminates. 


Seealso TApplication::EndModal, TApplication: a ad 
TApplication::PumpW aitingMessages 


MessageLoopResult 

int MessageLoopResult; 

MessageLoopResult is set by a call to EndModal. It contains the value that is returned by 
MessageLoop and BeginModal. 


Seealso TApplication::BeginModal, TApplication: -EndModal, 
TApplication::MessageLoop 
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IdleAction 

virtual bool IdleAction(long idleCount); 

ObjectWindows calls IdleAction when no messages are waiting in the queue to be 
processed. You can override IdleAction to do background processing. However, the 
default action is to give the main window a chance to do idle processing as long as 
IdleAction returns true. idleCount specifies the number ae times IdleAction has been called 
between messages. | 


See also TFrameWindow::IdleAction 


InitApplication 

virtual void InitApplication(); 

ObjectWindows calls InitA pplication to initialize the first instance of the application. For 
subsequent instances, this member function is not called. 


The following sample program calls InitApplication the first time an instance of the 
program begins. 


class TTestApp : public TApplication { 

public: | 

TTestApp(): TApplication("Instance Tester") 
{strepy (WindowTitle, "Additional Instance") ;} 

protected: | 
char WindowTitle[20]; 

void InitApplication() {strepy (WindowTitle, "First Instance") ;} | 

void InitMainWindow() {MainWindow = new TFrameWindow(0, WindowTitle) ;} 
Ie | | 
static TTestApp App; 


InitInstance 
virtual void InitInstance(); 
Performs each instance initialization necessary for the application. Unlike 
InitApplication, which is called for the first instance of an application, InitInstance is 
called whether or not there are other executing instances of the application. InitInstance 
calls InitMainWindow, and then creates and shows the main window element by 
TWindow::Create and TWindow::Show. If the main window can't be created, a 

_ TXInvalidMainWindow exception is thrown. 


If you redefine this member function, be sure to explicitly call TApplication::InitInstance. 


Seealso TApplication::InitApplication, TApplication::InitMainWindow, 
TApplication::Run, TModule::;MakeWindow, TWindow::Show 


InitMainWindow 

virtual void InitMainWindow(); 

By default, InitMainWindow constructs a generic TFrameWindow object with the name of 
the application as its caption. You can redefine InitMainWindow to construct a useful 
main window object of TFrameWindow (or a class derived from TFrameWindow) and 
store it in MainWindow. The main window must be a top-level window; that is, it must 
be derived from TFrameWindow. A typical use is 
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virtual void TMyApp_InitMainWindow() { 
SetMainWindow(TMyWindow(NULL, Caption) ); 
} 


InitMainWindow can be overridden to create your own custom window. 


SetDocManager 
TFrameWindow* SetDocManager(TDocManager* docManager); 
Sets a pointer to the document manager object that invoked the application. 


Seealso T’Application::GetDocManager, TDocManager, TFrameWindow 


SetMainWindow 
TFrameWindow* SetMainWindow(TFrameWindow* window); 
Sets up a new main window and sets the window's WM_MAINWINDOW flag. 


Seealso TApplication::GetMainWindow, TFrameWindow 


Terminstance 
virtual int TermInstance(int status); 
Handles the termination of each executing instance of an ObjectWindows application. 


A nested class, TXInvalidMainWindow describes an exception that results from an 
invalid Window. This exception is thrown if there is not enough memory to create a 
window or a dialog object. InitInstance throws this exception if it can't initialize an 
instance of an application object. 


Public constructor 


Constructor 

TXInvalidMainWindow(); 

Constructs a TXInvalidMainWindow object with a default 
IDS_INVALIDMAINWINDOW message. 


Public member functions 


Clone 

virtual TXOwl* Clone(); 

Makes a copy of the exception object. Clone must be implemented in any class derived 
from TXOwl. 


Throw 
virtual void Throw(); 


Throws the exception object. Throw must be implemented in any class derived from 
TXOuwl. 
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TAutoFactory<>class ts olefacto.h 


A template class, TAutoFactory<> creates callback code for ObjectWindows classes. The 
application class is passed as the argument to the template. By itself, TAutoFactory<> 
does not provide linking or embedding support for era: automated 

_ applications. 


Although TAutoFactory<> simplifies the process of creating the callback function, you 
can write your own callback function or provide alternate implementation for any or all 
_ of TAutoFactory<>'s ia , | 


See also 
TComponentFactory typedef, TOcRegistrar class, TOleFactoryBase class 


Public member functions 


Create 
static |Unknown* Create(IUnknown* outer, uint32 options, uint32 d) 
Create is a TComponentFactory callback function that creates or destroys the application 
or creates objects. If an application object does not already exist, Create creates a new 
one. The outer argument points to the OLE2 [Unknown interface with which this object 
aggregates itself. If outer is 0, the new object is not aggregated, or it will become the 
main object. 


The options argument indicates the application's mode while it is running. The values for 
options are either set from the command line or set by ObjectComponents. They are 
passed in by the "Registrar" to this callback. The application looks at these flags to know 

how to operate, and the factory callback looks at them to know what to do. For example, 
a value of amExeMode indicates that the server is running as an .EXE either because it 
was built as an EXE or because it is a .DLL that was launched by an .EXE stub and is 
now running as an executable program. See TOcAppMode enum for a description of the 
possible values for the options argument. | | 


If the application already exists, Create returns the application's OLE interface and 
registers the options from TOcAppMode enum which contains OLE-related flags used in 
the application's command line. For example, the amAutomation flag tells the server to 
register itself as a single-user application. (In general, these flags tell the application 
whether it has been run as a server, whether it needs to register itself, and so on.) 


The id argument, which is not used for TAutoFactory, is always 0. 
Seealso TAutoFactory: ca a TOcAppMode enum | 


CreateApp 

static T* CreateApp(uint32 options); | 

CreateApp creates a new automated application. By default, it creates a new application 
of template type T with no arguments. The options argument is one of the OT eee 
enum values, for example, amRun, amAutomation, and so on that indicate the 
application's mode when running. 


See also TAutoFactory: ‘DestroyApp, TOcAppMode enum 
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DestroyApp 
static void DestroyApp(T* app); 
Destroys the previously created application referred to in app. 


operator TComponentFactory 

operator TComponentFactory(); 

Converts the object into a pointer to the factory. ObjectComponents uses this pointer to 
create the automated object. 


Seealso ‘TAutoFactory::CreateApp 


An ObjectWindows struct, TBandInfo is used to pass information to a printer driver that 
supports banding. TBandInfo is declared as follows: 


struct TBandInfo { 
bool HasGraphics; 
bool HasText; 

TRect GraphicsRect; 
iF 


HasGraphics is true if graphics are (or are expected to be) on the page or in the band; 
otherwise, it is false. 


HasText is true if text is (or is expected to be) on the page or in the band; otherwise, it is 
false. 


GraphicsRect defines the bounding region for all graphics on the page. 
Seealso TPrintDC::BandInfo, TPrintDC::NextBand 


TBitmap class = gdiobjec.h 


Form 1 


Form 2 


TBitmap is the GDI bitmap class derived from TGdiObject. TBitMap can construct a 
bitmap from many sources. TBitmap objects are DDBs (device-dependent bitmaps), 
which are different from the DIBs (device-independent bitmaps) represented by TDib 
objects. 


Public constructors 


Constructors 


-TBitmap(HBITMAP handle, TAutoDelete autoDelete = NoAutoDelete); 


Creates a [Bitmap object and sets the Handle data member to the given borrowea andle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 


TBitmap(const TClipboard& clipboard); 
Creates a TBitmap object with values from the given Clipboard. 
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Form 3 TBitmap(const TBitmap& bitmap); 
Creates a copy of the given bitmap object. 


Form 4  TBitmap(int width, int height, uint8 planes=1, uint8 bitCount=1, void far* bits= 0): 
Creates a bitmap object from bitCount bits in the bits buffer with the given width, height, 
and planes argument values. 

Form5  TBitmap(const BITMAP far* bitmap); 
Creates a bitmap object with the values found in the given bitmap structure 


Form6 TBitmap(const TDC& De, int width, int height, bool discardable = false); 
Creates a bitmap object for the given device context with the given argument values. 


Form7  TBitmap(const TDC& De, const TDib& dib, uint32 usage=CBM_INIT); 
Creates a bitmap object for the given device context with the given dib and usage 
argument values. , 


Form 8. TBitmap(const TMetaFilePict® metaFile, TPalette& palette, const TSize& size); 
Creates a bitmap object from the given metaFile using the given palette oe size 
arguments. | 


— Form9 = TBitmap(const TDib& dib, const TPalette* palette = 0); 
Creates a bitmap object from the given dib and palette arguments. A working palette 
constructed from the DIB's color table is used if no palette is supplied. The default 
system palette can also be passed using &TPalette::GetStock(TPalette::Default), 
Form10 TBitmap(HINSTANCE instance, TResID resID); 
| Creates a bitmap object for the given application instance from the given resource. 


Seealso TClipBoard::GetClipboardData, TDC, TDib, TGdiObject::Handle, 
TGdiObject::ShouldDelete, TPalette, BITMAP struct 


Public member functions 


BitsPixel | 
uint8 BitsPixel() const; 
Returns the number of bits per pixel in this PinTaP: 


See also TBitmap: ;GetObject 


GetBitmapBits 
uint32 GetBitmapBits(uint32 count, void far* bits) const; 
Copies up to count bits of this bitmap to the buffer bits. 


GetBitmapDimension 

bool GetBitmapDimension(TSize& size) const; 

Retrieves the size of this bitmap (width and height, eieasued in tenths of eedinnasteis) 
and sets it in the size argument. Returns true if the call is successful; otherwise returns 
false. 


See also TSize 


~ GetObject 
bool GetObject(BITMAP fark bitmap) const, 
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Retrieves data (width, height, and color format) for this bitmap and sets it in the given 
BITMAP structure. To retrieve the bit pattern, use GetBitmap Bits. 


Seealso ‘BitMap::GetBitmapBits, BITMAP struct 


Height 
int Height() const; 
Returns the height of this bitmap. 


See also TBitmap::GetObject 


operator << 

TClipboard& operator <<(TClipboard& clipboard, TBitmap& bitmap); 

Copies the given bitmap to the given clipboard argument. Returns a reference to the 
resulting Clipboard, which allows normal chaining of <<. 


Seealso Clipboard 


operator HBITMAP() 

operator HBITMAP() const; 

Typecasting operator. Converts this bitmap's Handle to type HBITMAP (the data type 
representing the handle to a physical bitmap). 


Planes 
uint8 Planes() const; 
Returns the number of planes in this bitmap. 


See also Bitmap::GetObject 


SetBitmapBits 
uint32 SetBitmapBits(uint32 count, const void far* bits): 
Copies up to count bits from the bits buffer to this bitmap. 


SetBitmapDimension 

bool SetBitmapDimension(const TSize& size, TSize far* oldSize=0); 

Sets the size of this bitmap from the given size argument (width and height, measured in 
tenths of millimeters). The previous size is set in the oldSize argument. Returns true if the 
call is successful; otherwise returns false. 


Seealso TSize 


ToClipboard 
void ToClipboard(TClipboard& clipboard): 
Copies this bitmap to the given Clipboard. 


Seealso TClipboard::SetClipboardData 
Width 

int Width() const; 

Returns the width of this as 


Seealso Bitmap::GetObject 
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Protected constructor 


Constructor 
TBitMap(); 
Protected constructor for a TBitmap object. 


Protected member functions 


Create | 

void Create(const TDib& dib, const TPalette &palette); 

void Create(const TBitmap &src); 

Creates a bitmap handle from the given argument objects. 


Seealso Dib, TPalette 


Operators 


operator << 

TClipboard& operator <<(TClipboard& clipboard, TBitmap& bitmap); | 

Copies the given bitmap to the given clipboard argument. Returns a relarcuce to the” 
resulting Clipboard, which allows normal chaining of <<. 


Seealso TClipboard 


operator HBITMAP() 

operator HBITMAP() const; 

Typecasting operator. Converts this bitmap's Handle to Pe HBITMAP (the data type 
representing the handle to a physical bitmap). 


TBitmapGadget class —__ bitmapga.h 


Derived from TGadget, TBitmapGadget is a ne gadget that can display an aneaye of 
bitmap i images one at a time. 


Public constructor and destructor 


Constructor 

TBitmapGadget(TResld bmpResld, int id, TBorderStyle borderStyle, TResIid siaDNatie int saiainages 
int startimage); 

Constructs a TBitmapGadget and sets the current image to the beginning i image 

(startImage) in the array of images. Then, sets the border style to the current TGadget 

border style and numImages to the number of images in the array. _ 


Destructor 
~TBitmapGadget(); 
Deletes the array of images. 
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Public member functions 


Selectilmage 

int SelectImage(int imageNum, boo! immediate); 

Determines the current image and repaints the client area if the image has changed. 
Updates the client area if the image has changed. 


SysColorChange 

void SysColorChange(); 

When the system colors have been changed, SysColorChange i is called by the gadget 
window's EvSysColorChange so that bitmap gadgets can be rebuilt and repainted. 


Protected member functions 


GetDesiredSize 

void GetDesiredSize(TSizeé& size); 

Calls TGadget::GetDesiredSize, which determines how big the bitmap gadget can be. The 
gadget window sends this message to query the gadget's size. If shrink-wrapping is 
requested, GetDesiredSize returns the size needed to accommodate the borders and 
margins. If shrink-wrapping is not requested, it returns the gadget's current width and 
height. TGadgetWindow needs this information to determine how big the gadget needs 
to be, but it can adjust these dimensions if necessary. If WideAsPossible is true, then the 
width parameter (size.cx) is ignored. 


Paint 
void Paint(TDC& dc); 
Paints the gadget's border and the contents of the bitmap. 


Seealso TGadget::Paint 
SetBounds 
void SetBounds(TRect& r); 


Calls TGadget::SetBounds and passes the dimensions of the bitmap gadget. SetBounds 
informs the control gadget of a change in its bounding rectangle. 


Seealso TGadget::SetBounds 


TBitSet class bitset.h 


Form 1 


TBitSet sets or clears a single bit or a group of bits. You can use this class to set and clear 
option flags and to retrieve information about a set of bits. The class TCharSet performs 


‘similar operations for a string of characters. 


Public constructors 
Constructors 


TBitSet(); | 
Constructs a T'BitSet object. 
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TBitSet class 


Form 2 


Form 1 


Form 2 


Form 1 


Form 2 


| Form 1 


Form 2 


Form 1 


Form 2 


TBitSet(const TBitSet& bs); | 
Constructs a TBitSet object as a copy: of soe TBitSet. 


Public member functions 


Disableltem 
void Disableltem(int item); 
Clears a single bit at item. 


void Disableltem(const TBitSet& bs); 
Clears the set of bits enabled in bs. 


Enableltem | 
void Enableltem(int item); 
Sets a single bit at item. 


void Enableltem(const TBitSet& bs); 
Sets the set of bits enabled in bs. 


Has 
int Has(int item); 
Is nonzero if item is in the set of bits. 


IsEmpty | 
int TBitSet::lsEmpty(); 
Is nonzero if the set is empty; otherwise, is 0. 


operator += 

TBitSet& operator +=(int item); 

Calls EnablelItem to set a bit in the copied set. Returns a reference to the copied TBitSet 
object. | 


TBitSet& operator +=(const TBitSet& bs); 
Calls Enableltem to set the bits nai in bs. Returns a reference to the copied TBitSet 
object. 


operator —= 
TBitSet& operator —= “(int item); 
Calls Disableltem to clear a bit in the set. Returns a reference to the copied TBitSet object. 


TBitSet& operator —=(const TBitSet& bs); 
Calls Disableltem to clear the bits enabled in bs. Returns a reference to the copied TBitSet 
object. 


operator &= 
TBitSet& operator &=(const TBitSet&); 
ANDs all the bits in the copied set and returns a reference to the copied TBitSet object. 


operator |= 
TBitSet& operator |=(const TBitSet&); 
ORs all of the bits in the copied set and returns a reference to the copied TBitSet object. 
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operator ~ 

TBitSet operator ~(const TBitSet&); 

Returns the set of bits that is the opposite of a specified set of bits. For example, if the set 
of bits is 01010101, the returned set is 10101010. Returns a reference to the copied TBitSet 
object. 


Defined in vbxctl.h and virtually derived from TModule, TBIVbxLibrary handles loading 
and initializing of BIVBX10.DLL. If you want to use VBX controls, construct a 
TBIVbxLibrary object with the same scope as your application. For example, 


int OwlMain(int, char**) 
{ 
TBIVbxLibrary vbxLib; 
return TTestApp().Run(); 
i 


Public constructor and destructor 


Constructor 
TBIVbxLibrary(); 
Constructs a TBIVbxLibrary object. 


Destructor 
~TBIVbxLibrary(); 
Destroys a TBIVbxLibrary object. 


TBrush class gdiobjec.h 


Form 1 


Form 2 


Form 3 


The GDI Brush class is derived from TGdiObject. TBrush provides constructors for 
creating solid, styled, or patterned brushes from explicit information. It can also create a 
brush indirectly from a borrowed handle. 


Public constructors 


Constructors 

TBrush(HBRUSH handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TBrush object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. | 


TBrush(TColor color); | 
Creates a solid TBrush object with the given color. To save a brush creation this 
constructor uses a cache that can detect any color that matches a stock color. 


TBrush(TColor color, int style); 
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Form 4 
Form 5 


Form 6 


TButton Class 


Py ‘TButton Class 


Creates a hatched TBrush ebeat with the given styl and color. 


TBrush(const TBitmapé& pattern): 
Creates a patterned TBrush object with the given pattern. 


- TBrush(const TDib& pattern); 


Creates a patterned TBrush object with the given DIB pattern. 
TBrush(const LOGBRUSH far* logBrush); 


Creates a TBrush object with values from the given logBrush. 


See also TBitmap, TColor, TDib, TGdiObject: ‘Handle, TGdiObject: ‘ShouldDelete, 
LOGBRUSH struct 


Public member functions _ 


GetObject 
bool GetObject(LOGBRUSH far& logBrush) const; 


Retrieves information about this brush object and places it in the given LOGBRUSH 


structure. Returns true if the call is successful; otherwise returns false. 
See also TGdiObject::GetObject, LOGBRUSH struct 


operator HBRUSH() 
operator HBRUSH() const; 
Typecasting operator. Converts this brush's Handle to type HBRUSH (the data type 
representing the handle to a physical brush). | 


UnrealizeObject 

bool UnrealizeObject(); 

Directs the GDI to reset the origin of this brush the next time it is selected. Returns true if 
call is successful; otherwise returns false. | 


TButton is an interface class that represents a pushbutton interface element. You must 


use a TButton to create a button control in a parent TWindow. You can also use a TButton 


to facilitate communication between your application and the button controls of a 
TDialog. This class is streamable. 


There are two types of pushbuttons: regular and default. ae buttons have a thin 


border. Default buttons (which le the default action of the window) have a thick 


border. 


Public data members 
isDefPB 


bool IsDefPB; 
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button.h 


Form 1 


Form 2 


TButton Class 


Indicates whether the button is to be considered the default pushbutton. Used for 
owner-draw buttons, IsDefPB is set by a TButton constructor based on 
BS_DEFPUSHBUTTON style setting. 


Public constructors 


Constructors 
TButton(Window *parent, int Id, const char far* text, int X, int Y, int W, int H, bool isDefautt = false, 

TModule* module = 0); 
Constructs a button object with the supplied parent window (parent), control ID (Id), 
associated text (text), position (X, Y) relative to the origin of the parent window's client 
area, width (W), and height (H). If IsDefault is true, the constructor adds 
BS_DEFPUSHBUTTON to the default styles set for the TButton (in Attr.Style). 
Otherwise, it adds BS PUSHBUTTON. 


TButton(TWindow* parent, int resourcelD, TModule* module = 0); 

Constructs a TButton object to be associated with a button control of a TDialog. Calls 
DisableTransfer to exclude the button from the transfer mechanism because there is no 
data to be transferred. 


The resId parameter must correspond to a button resource that you define. 
Seealso TControl::TControl | 


Protected data member 


IsCurrentDefPB 
bool IsCurrentDefPB; 
Indicates whether the current button is the default pushbutton. 


Protected member functions 


BMSetStyle 

LRESULT BMSetStyle(WPARAM, LPARAM): 

Because a button can't have both owner-drawn and pushbutton styles, BMSetStyle keeps 
track of the style if the button is owner-drawn and the system tries to set the style to 
BS_DEFPUSHBUTTON. BMSetStyle sets IsCurrentDefPB to true if the button style is 
BS_DEFPUSHBUTTON. 


EvGetDigCode 

uint EvGetDigCode(MSG far’); 

Responds to WM_GETDLGCODE messages that are sent to a dialog box associated 
with a control. EvGetDlgCode allows the dialog manager to intercept a message that 
would normally go to a control and then ask the control if it wants to process this 
message. If not, the dialog manager processes the message. The msg parameter indicates 
the kind of message, for example a control, command, or button message, sent to the 
dialog box manager. 
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EvGetDgCode returns a code that indicates how the button i is to be treated. If this is the 
currently used pushbutton, EvGetDigCode returns emene oS _DEFPUSHBUTTON or 
DLGC_UNDEFPUSHBUTTON. 


See also DLGC_xxxx dialog control message constants 


GetClassName 

char far* GetClassName(); 

Overrides TWindow's GetClassName function. If BWCC is enabled returns the name Sa 
TButton's registration class, "BUTTON_CLASS"; if BWCC isn't enabled, returns the 
name "BUTTON." 


SetupWindow 

void SetupWindow(); 

Overrides TWindow’s SetupWindow function. If the button i is the default puehbuien and 
an owner-drawn button, SetupWindow sends a DM_SETDEFID message to the parent 
window. 


Response table entries 


EV_WM_GETDLGCODE | EVGetDlgCode 
EV_MESSAGE (BM_SETSTYLE, BMSetStyle) | BMSetStyle 


-TButtonGadget class — _ buttonga.h 


Derived from TGadget, TButtonGadgets represent buttons that you can click on or off. 
You can also apply attributes such as color, style, and shape (notched or unnotched) to 
your button gadgets. 


In general, button gadgets are classified as either command or attribute buttons. 
Attribute buttons include radio buttons (which are considered exclusive), or check 
boxes (which are nonexclusive). The public data member, TT ype, enumerates these 
button types. 


TButtonGadget contains several functions that let you change the style of a button. Use 
SetAntialiasEdges to turn antialiasing on and off, SetNotchCorners to control corner 
notching, and SetShadowStyle to change the style of the button shadow. 


TButtonGadget objects respond to mouse events in the following manner: when a mouse 
button is pressed, the button is pressed; when the mouse button is released, the button is 
released. Commands can be entered only when the mouse button is in the "up" state. 
When the mouse is pressed, TButtonGadget objects capture the mouse and reserve all 
mouse messages for the current window. When the mouse button is up, button gadgets | 
release the capture for the current window. The public data member, TState, enumerates 
the three button states. 
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Type definitions 


TShadowStyle 
enum TShadowStyle; 
Enumerates button shadow styles—either single (1) or double (2) shadow borders. 


TState 

enum TState; 

TState enumerates the three button positions during which the button can be pressed: 
up (0), down (1), and an indeterminate state (2). A nonzero value indicates a highlighted 
button. 


TType 
enum TType; 
Enumerates the types of buttons: command, exclusive, or nonexclusive. 


Public constructor and destructor 


Constructor 

TButtonGadget(TResid bmpResld, int id, TType type = Command, bool enabled = false, TState state = Up, bool 
repeat = false); 

Constructs a TButtonGadget object using the specified bitmap ID, button gadget ID, and 
type, with enabled set to false and in a button-up state. The button isn't enabled—its 
initial state before command enabling occurs. 


Destructor 
~TButtonGadget(); 
Deconstructs a TButtonGadget object. 


Seealso TButtonGadget::TState 


Public member functions 


CommandEnable 

void CommandEnable(); 

Enables the button gadget to capture messages. Calls SendMessage to senda 
WM_COMMAND_ENABLE message to the gadget window's parent, passing a 
TCommandEnable: EoCommandEnable message for this button. 


GetButtonState 

TState GetButtonState(); 

Returns the state of the button. If 0, the button is up, if 1, the puter is down, if 2, the 
state is indeterminate. 


Seealso TButtonGadget::TState 
GetButtonType 
TType GetButtonType(); 


Returns the button type as 1 if the button is a command, 2 if exclusive, or 3 if 
nonexclusive. 
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SetAntialiasEdges | 
SetAntialiasEdges(bool anti = true); 
Turns the antialiasing of the button bevels on or off. By default, antialiasing is on. 


SetButtonState 

void SetButtonState(TState); | 

Sets the state of the button. If the state has changed, the button is exclusive, and is in the 
down state, checks that the button is exclusive, sets State, and calls Invalidate to mark the 
changed area of the gadget for repainting. 


See also TButtonGadget::TState 


SetNotchCorners 

void SetNotchCorners(bool NotchCorners = true);. 

By default, SetNotchCorners implements notched corners for buttons. To repaint the 
frame of the button if the window has already been created, call InvalidateRect with the 
Bounds rectangle. 


Seealso TButtonGadget::Invalidate, TGadget::InvalidateRect, TGadget::Paint 


SetShadowStyle 

void SetShadowStyle(TShadowStyle): 

Sets the button style to a shadow style which, by default, is s DoubleShadow. Sets the left 
and top borders to 2 and the right and bottom borders to ShadowStyle + 1. 


SysColorChange | 

void SysColorChange(); 

SysColorChange responds to an EvSysColorChange message forwarded by the owning 
TGadgetWindow by setting the dither brush to zero. If a user-interface bitmap exists, 
SysColorchange deletes and rebuilds it to get the new button colors. 


Protected data members 


AntialiasEdges 
bool AntialiasEdges; 
Is true if antialiasing is turned on. 


BitmapOrigin 
TPoint BitmapOrigin; 
Points to the x and y coordinates of the bitmap used for this Bulton gadget. 


CelArray 
TCelArray* CelArray; 
The array of cels used by this button gadget. 


NotchCorners 

bool NotchCorners; 

Initialized to 1, NoicnComnenst is 1 if the button gadget has notched corners or 0 if it 
doesn’ thave notched corners. 
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Pressed 
bool Pressed; 
Initialized to 1, Pressed is 1 if the button is released or 0 if it isn t released. 


See also TButtonGadget::Activate, TButtonGadget::BeginPressed, 
TButtonGadget::CancelPressed 


Repeat 
bool Repeat; 
Initialized to 1, Repeat stores the repeat count for keyboard events. 


Resid 
TResld Resid; 
Holds the resource ID for this button gadget's bitmap. 


ShadowStyle 
TShadowStyle Shadowstyle; 
Holds the shadow style for the button—1 for single and 2 for double. 


State 
TState State; 
Holds the state of the button—either up, down, or indeterminate. 


Type — 
TType Type; 
Holds the type of the button—either command, exclusive, or nonexclusive. 


Protected member functions 


Activate 

virtual void Activate(TPoint& p); 

Invoked when the mouse is in the "up" state, Activate sets Pressed to false, changes the 
state for attribute buttons, and paints the button in its current state. To do this, it calls 
CancelPressed, posts a WM_COMMAND message to the gadget window's parent, and 
sends menu messages to the gadget window's parent. 


See also TButtonGadget::Pressed 


BeginPressed | 

virtual void BeginPressed(TPoint& p); 

When the mouse button is pressed, Beginpressed sets ee to true, paints the pressed 
button, and sends menu messages to the gadget window's parent. 


Seealso TButtonGadget::Pressed 


BuildCelArray 

virtual void BuildCelArray(); 

Builds a cel array using the resource bitmap as the base glyph. Any existing cel array 
should be deleted if a replacement is built. 


Seealso TCelArray 
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CancelPressed 

virtual void CancelPressed(TPoint& p); 

When the mouse button is released, CancelPressed sets Pressed to false, paints the button, 
and sends menu messages to the gadget window's parent. | 


Seealso TButtonGadget::Pressed_ 


GetDesiredSize 

void GetDesiredSize(TSize& size); 

Stores the width and height (measured in pixels) of - button gadget in size. Calls 
TGadget's GetDesiredSize to calculate the relationship between one peclane)e and 
another. 


GetGlyphDib 

virtual TDib* GetGlyphDib(); 

Supplies the glyphdib. You can override this function to get a different dib, or to change 
the attributes of the dib, such as the colors, and so on. 


Invalidate 

void Invalidate(); | 

If a button is pressed or the state of the button is changed, Invalidate invalidates (marks. 
for repainting) the changed area of the gadget. Invalidate only invalidates the area that 
changes. To repaint the entire gadget, call TGadget::InvalidateRect and pass the 
rectangle's boundaries. 


Seealso TButtonGadget::TState, TGadget::InvalidateRect 


LButtonDown 

void LButtonDown(uint modKeys, TPoint& p); 

Overrides TGadget member function and responds to a left mouse button click by calling 
BeginPressed. 


—Seealso TButtonGadget::BeginPressed 


LButtonUp » 

void LButtonUp(uint modKeys, TPoint& p); 

Overrides [Gadget member functions and responds to a release of the left mouse button 
by calling Activate. 


Seealso TButtonGadget: Naive 


MouseEnter 

void MouseEnter(uint modKeys, TPoint& p); 

Called when the mouse enters the boundary of the button gadget. modKeys indicates the 
virtual key information and can be any combination of the following values: 
MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON, or MK_ SHIFT. 

p indicates where the 1 mouse entered the button gadget. 


MouseLeave 

void MouseLeave(uint modKeys, TPoint& p); 

Called when the mouse leaves the boundary of the button gadget. modKeys indicates the 
virtual key information and can be any combination of the following values: 
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MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON, or MK_SHIFT. 
p indicates the place where the mouse left the button gadget. 


MouseMove 

void MouseMove(uint modKeys, TPoint& p); 

Calls TGadget::MouseMove in response to the mouse being dragged. If the mouse moves 
off the button, MouseMove calls CancelPressed. If the mouse moves back onto the button, 
MouseMove calls BeginPressed. 


Seealso TButtonGadget::BeginPressed, TButtonGadget::CancelPressed 


Paint 

void Paint(TDC& de); 

Gets the width and height of the window frame (in pixels), calls GetImageSize to retrieve 
the size of the bitmap, and sets the inner rectangle to the specified dimensions. Calls 
TGadget::PaintBorder to perform the actual painting of the border of the control. Before 
painting the control, Paint determines whether the corners of the control are notched, 
and then calls GetSysColor to see if highlighting or shadow colors are used. Paint 
assumes the border style is plain. Then, Paint draws the top, left, right, and bottom of the 
control, adjusts the position of the bitmap, and finishes drawing the control using the 
specified embossing, fading, and dithering. 


ReleaseGlyphDib 
virtual void ReleaseGlyphDib(TDib* glyph); | 
Releases the glyph dib depending on how it was obtained by GetGlyphDib. 


SetBounds 

void SetBounds(TRect& 1); 

Gets the size of the bitmap, calls TGadget::SetBounds to set the boundary of the rectangle, 
and centers the bitmap within the button’s rectangle. 


Seealso TGadget::SetBounds 


TButtonGadgetEnabler class __tionga.cpp 


Derived from TCommandEnabler, TButtonGadgetEnabler serves as a command enabler for 
button gadgets. The functions in this class modify the text, check state, and sees 
of a button gadget. 


Public constructor 


Constructor 

TButtonGadgetEnabler(HWND hWndReceiver, TButtonGadget* g) 

Constructs a TButtonGadgetEnabler for the specified gadget. hWndReceiver is the window 
receiving the message. 
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a etaue class: 


| Protected data dined: 


gadget 
TButtonGadget* gadget; 
The button gadget being enabled or disabled. 


Public member functions 


| Enable 


void Enable(bool enable); 
Overrides TCommandEnable::Enable. Enables or disables the keyboard, mouse input and 
appearance of the corresponding button gadget. 


SetCheck 

void SetCheck(int state) : f 

Overrides TCommandEnable::SetCheck. Changes the check state of the corresponding 
button gadget. 


SetText | 

void SetText(const char far*) | 
Overrides TCommandEnable::SetText. Changes the text of the corresponding button 
gadget. 


TOelArrayclass array 


Form 1 


TCelArray is a horizontal array of cels (a unit of animation) created by slicing a portion of 
or an entire bitmap into evenly sized shapes. Gadgets such as buttons can use a 
TCelArray to save resource space. TCelArray’s functions let you control the dimensions 
of each cel and determine if the cel can delete the bitmap. : 


Offset from the top left corner of the bitmap 


Bitmap 


Public constructors and destructor 


Conetucters 


_TCelArray(TBitmap* bmp, int numCels, TSize celSize = 0, TPoint Offset = 0, TAutoDelete = AutoDelete); 


Constructs a TCelArray from a bitmap by slicing the bitmap into a horizontal array of 
cels of a specified size. If autoDelete is true, TCelArray can automatically delete the 
bitmap. The ShouldDelete data member defaults to true, ensuring that the handle will be 
deleted when the bitmap is destroyed. 


Form 2 TCelArray(TDib& dib, int numCels); 
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TCelArray class 


Constructs a TCelArray from a DIB (Device Independent Bitmap) by slicing the DIB into 
a horizontal array of evenly sized cels. 


TCelArray(const TCelArray& src); 
Constructs a TCelArray as a copy of an existing one. If the original TCelArray owned its 
bitmap, the constructor copies this bitmap; otherwise, it keeps a reference to the bitmap. 


Destructor 

virtual ~TCelArray(); 

If ShouldDelete is true (the default value), the bitmap is deleted. If ShouldDelete is false, 
no action is taken. 


Public member functions 


CelSize 
TSize CelSize() const; 
Returns the size in pixels of each cell. 


CelOffset 

TPoint CelOffset(int cels); 

Returns the position of the upper left corner of a given cel relative to the upper left 
corner of the bitmap. 


CelRect 

TRect CelRect(int cel) const; 

Returns the upper left and lower right c corner of a given cell relative to the upper left — 
corner of the bitmap. 


NumCels 
int NumCels() const; 
Returns the number of cels in the array. 


Offset | 
TPoint Offset() const; 
Returns the offset of the entire CelArray. 


operator [] 
TRect operator [](int cel) const; 
Returns CelRect. 


operator = 
TCelArray& operator =(const TCelArray&); 
Returns TCelArray. 


operator TBitmap&() 
operator TBitmap&(); 
Returns a reference to the bitmap. 


SetCelSize 
void SetCelSize(TSize size); 
Sets the size of each cel in the array. 
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SetOffset 
void SetOffset(TPoint offs); 
Sets the offset for the cels in the array. 


SetNumCels 
void SetNumCels(int numCels); 
Sets the number of cels in the array. 


Protected data members 


Bitmap 


TBitmap* Bitmap; 
Points to the bitmap. 


CSize 
TSize CSize; 
The size of a cell in the array. 


Offs 

TPoint Offs; 

Holds the offset of the upper left corner of the cel array from the upper left corner of the 
bitmap. 


NCels 
int NCels; 
The number of cells in the cel array. 


ShouldDelete 
bool ShouldDelete; 
Is true if the destructor needs to delete the bitmap associated with the cel array. 


Form 1 


Form 2 


Form 3 


Derived from TBitSet, TCharSet sets and clears bytes for a group of characters. You can 
use this class to set or clear bits in a group of characters, such as the capital letters from 
"A" through "Z" or the lowercase letters from "a" through "z." The class TBitSet performs 
similar operations for a group of bits. | 


Public constructors 


Constructors 
TCharSet(); 
Constructs a TCharSet object. 


TCharSet(const TCharSet&); 
Copy constructor for a TCharSet object. 


TCharSet(const char far* str); 
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Constructs a string of characters. 


Public member function 


operator != 

int operator !=(const TBitSet& bs1, const TBitSet& bs2): 

ORs all of the bits in the copied string and returns a reference to the copied TCharSet 
object. | 


TCheckBox class checkbox.h 


Form 1 


Form 2 


TCheckBox is a streamable interface class that represents a check box control. Use 
TCheckBox to create a check box control in a parent window. You can also use TCheckBox 
objects to more easily manipulate check boxes you created in a dialog box resource. 


Two-state check boxes can be checked or unchecked; three-state check boxes have an 
additional grayed state. TCheckBox member functions let you easily control the check 
box's state. A check box can be in a group box (a TGroupBox object) that groups related 
controls. | 


Public data member 


Group 

TGroupBox* Group; 

If the check box belongs to a group box (a TGroupBox object), Group points to that object. 
If the check box is not part of a group, Group is zero. 


Seealso TGroupBox::TGroupBox 


Public constructors 


Constructors 

TCheckBox(TWindow* parent, int Id, const char far’ title, int x, int y, int w, int h, TGroupBox* group = 0, 
TModule* module = 0); 

Constructs a check box object with the specified parent window (parent), control ID (Id), 

associated text (title), position relative to the origin of the parent window's client area (x, 

y), width (w), height (1), associated group box (group), and owning module (module). 

Invokes the TButton constructor with similar parameters. Sets the check box's style to 

WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTOCHECKBOxX. 


TCheckBox(TWindow* parent, int resourceld, TGroupBox* group = 0, TModule* module = 0); 

Constructs an associated TCheckBox object for the check box control with a resource ID 
of resourceld in the parent dialog boxSets Group to group then enables the data transfer 
mechanism by calling EnableTransfer. 


Seealso Button::TButton, TWindow::EnableTransfer 
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Public member functions 


Check 

void Check(); 

Forces the check box to be checked by calling SetCheck with the value of BF "CHECKED. 
Notifies the associated group box, if there is one, that the state was changed. 


See also TCheckBox::GetCheckTCheckBox_GetCheck, 
TCheckBox::ToggleTCheckBox_Toggle, TCheckBox: ‘UncheckTCheckBox _Uncheck, 
TGroupBox: ‘SelectionChangedTGroupBox_ SelectionChanged 


GetCheck | 
uint GetCheck() const; 
Returns the state of the check box. 


TCheckBox check states 


Unchecked BF_UNCHECKED 
Grayed , BF_GRAYED 


See also TCheckBox::SetCheck 


GetState 
uint GetState() const; 
Returns the check, focus, and highlight state of the check box. 


Seealso TCheckBox::SetState 


SetCheck 

void SetCheck(uint check); — 

Forces the check box into the state specified by check. See the table in GetCheck for 
possible values of check. | | 


See also TCheckBox::GetCheck 


SetState 
void SetState(uint state); 
Sets the check, focus, and highlight state of the check box. 


See also TCheckBox: -GetState 


SetStyle 
void SetStyle(uint style, bool redraw); 
Changes the style of the check box. 


Toggle 

void Toggle(); 

Toggles the check box between checked and unchecked if it is a two-state check box; 
toggles it between checked, unchecked, and gray if it is a three-state check box. 
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Seealso TCheckBox::SetCheck 


Transfer 

uint Transfer(void* buffer, TTransferDirection direction); 

Overrides TWindow::Transfer. Transfers the check state of the check box to or from buffer, 
using the values specified in the table in GetCheck. If direction is tdGetDate, the check box 
state is transferred into the buffer. If direction is tdSetData, the check box state is changed 
to the settings in the transfer buffer. 


Transfer returns the size of the transfer data in bytes. To get the size without actually 
transferring the check box, use tdSizeData as the direction argument. 


Uncheck 

void Uncheck(); 

Forces the check box to be unchecked by calling SetCheck with a value of 
BF_UNCHECKED. Notifies the associated group box, if there is one, that the state has 
changed. 


Seealso TCheckBox::Check, TCheckBox::SetCheck, TCheckBox::Toggle 


Protected member functions 


BNClicked 

void BNClicked(); 

Responds to notification message BN_CLICKED, indicating that the user clicked the 
check box. If Group isn't 0, BNClicked calls the group box's SelectionChanged member 
function to notify the group box that the state has changed. 


See also TGroupBox::SelectionChanged 


EvGetDigCode 

uint EvGetDigCode(MSG far* msg); | 

Overrides TButton’s response to the WM_GETDLGCODE message, an input procedure 
associated with a control that is not a check box, by calling DefaultProcessing. The msg 
parameter indicates the kind of message, for example a control, command, or check box 
message, sent to the dialog box manager. 


EvGetDlgCode returns a code that indicates how the check box is to be treated. 


Seealso TButton::EvGetDlgCode, TWindow::DefaultProcessing, DLGC_xxxx dialog 
control message constants 


GetClassName 

char far* GetClassName(); 

If BWCC is enabled, TCheckBox returns CHECK CLASS. If BWCC is not enabled, 
returns "BUTTON. . 
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Response table entries 


EV_NOTIFY_AT_CHILD (BN_CLICKED, BNClicked) BNClicked 
EV_WM_GETDLGCODE EVGetDlgCode 
TChooseColorDialog class — | chooseco.h 


TChooseColor Dialog objects represent modal dialog box interface elements that allow 
color selection and custom color adjustment. TChooseColorDialog can be made to appear 
modeless to the user by creating the dialog's parent as an invisible pop-up window and 
making the pop-up window a child of the main application window. 
TChooseColorDialog uses the TChooseColor:: ‘TData struct to initialize the dialog box with 
the user's color selection. 


Public constructors 


Constructor 
TChooseColorDialog(TWindow* parent, TData& data, TResld templatelD = 0, const char far* title = 0, 
TModule* module = 0); 
Constructs a dialog box with specified parent window, data, resource identifier, 
_ window caption, and module ID. Sets the attributes of the dialog box based on info in 
the TChooseColor::TData structure. 


See also TChooseColorDialog::TData 


Public member function 


SetRGBColor 

void SetRGBColor(TColor color); 

Sets the current RGB color for the open dialog box by sending a SefRGBMsgld. You can 
use SetRGBColor to send a message to change the current color selection. 


Public data members 


cc 

CHOOSECOLOR cc; 

Stores the length of the TChooseColorDialog structure, the window that owns the dialog 
box, and the data block that contains the dialog template. It also points to an array of 16 
RGB values for the custom color boxes in the dialog box, and specifies the dialog-box 
initialization flags. 


See also TChooseColorDialog::TData | 


Data 
TData& Data; 
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Data is a reference to the TData object passed in the constructor. 
See also TChooseColorDialog::TData | 


SetRGBMsgld 
static uint SetRGBMsgld; 
Contains the ID of the registered message sent by SetRGBColor. 


Protected member functions 


DialogFunction 
bool DialogFunction(uint message, WPARAM, LPARAM); 
Returns true if a message is handled. 


Seealso TDialog::DialogFunction 


DoExecute 

int DoExecute(); 

If no error occurs, DoExecute copies flags and colors into Data and returns zero. If an 
error occurs, DoExecute returns the IDCANCEL with Data.Error set to the value returned 
from CommDIgExtendedError. 


EvSetRGBColor 

LPARAM EvSetRGBColor(WPARAM, LPARAM); 

Responds to the message sent by SetRGBColor by re the to the original class. 
This event handler is not in the response table. 


Response table entries 


The TChooseColorDialog response table has no entries. 


TChooseColorDialog::TData class chooseco.h 
Defines information necessary to initialize the dialog box with the user's color selection. 
Public data members 
Color 
TColor Color; 


Specifies the color that is initially selected when the dialog box is created. Contains the 
user's color selection when the dialog box is closed. 


CustColors 
TColor* CustColors; 
Points to an array of 16 colors. 


Error 
uint32 Error; 
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If the dialog box is successfully executed, Error is 0. Otherwise, it contains one of the 
following codes: 


“CDERR_DIALOGFAILURE a ed to create a ialog box. 


CDERR_FINDRESFAILURE Failed to find a specified resource. 
CDERR_LOADRESFAILURE Failed to loada specified resource. 
CDERR_LOCKRESOURCEFAILURE Failed to lock a specified resource. 
CDERR_LOADSTRFAILURE | Failed to load a specified string. 
Flags 
uint32 Flags; 


Flags can be a combination of the following values that control the appearance and 
functionality of the dialog box: 


cc _FULLOPEN Causes the entire dialog box to appear when the dialog box is created. 

CC_PREVENTFULLOPEN —_ Disables the "Define Custom Colors" push button. 

CC_RGBINIT | Causes the dialog box to use the color specified in rgbResult as the initial 
| color selection. ; 

CC_SHOWHELP Causes the dialog box to show the Help push button. 


See also TChooseColorDialog::Data 


TChooseFontDialog class |  choosefo.h 


A TChooseFontDialog represents modal dale ox interface elements that create a 
system-defined dialog box from which the user can select a font, a font style (such as 
bold or italic), a point size, an effect (such as strikeout or underline), and a color. 
TChooseFontDialog can be made to appear modeless by creating the dialog's parent as an 
invisible pop-up window and making the pop-up window a child of the main 
application window. TChooseFontDialog uses the TChooseFontDialog::T Data structure to 
initialize the dialog box with the user-selected font styles. 


Public constructor 


Constructor 


TChooseFontDialog(TWindow* parent, TData& data, TResiD templatelD = 0, const char far* title = 0, 
TModule* module = 0); 


Constructs a dialog box with specified data, parent window, resource identifier, 
window caption, and module ID. Sets the attributes of the dialog box based on the font 
information in the TChooseFontDialog::T Data structure. 


See also TChooseFontDialog::TData 
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Protected data members 


cf 

CHOOSEFONT cf; 

Contains font attributes. cf is initialized using fields in the TChooseFontDialog::TData 
structure. It stores the length of the structure, the window that owns the dialog box and 
the data block that contains the dialog template. It also specifies the dialog-box 
initialization flags. 


See also TChooseFontDialog::TData 


Data 
TData& Data; 
Data is a reference to the TData object passed in the constructor. 


Seealso TChooseFontDialog::TData 


Protected member functions 


CmFontApply 
void CmFontApply(); 
Default handler for the third pushbutton (the Apply button) in the dialog box. 


DialogFunction 
bool DialogFunction(uint message, WRARAM, LPARAM); 
Returns true if a dialog box message is handled. 


See also TDialog::DialogFunction 


DoExecute 

int DoExecute(); | 

If no error occurs, DoExecute copies the flag values and font information into Ddata, and 
returns IDOK or IDCANCEL. If an error occurs, DoExecute returns an error code from 
TChooseFontDialog::TData structure's Error data member. | 


‘Seealso TChooseFontDialog::TData 


Response table entries 


The TChooseFontDialog response table contains no entries. 


Defines information necessary to initialize the dialog box with the user's font selection. 
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| TChooseFontDialog::TData class 
Public data members 


Color 

TColor Color; 

Indicates the font color that is initially selected when the dialog box is created; contains 
the user's font color selection when the dialog box is closed. 


DC 
HDC DC; 
Handle to the device context from which fonts are obtained. 


Error 

uint32 Error; 

If the dialog box is successfully executed, Error returns 0. Otherwise, it contains one of 
the following codes: 


CDERR_DIALOGFAILURE ) Failed to create a dialog box. 

CDERR_FINDRESFAILURE Failed to find a specified resource. 
CDERR_LOCKRESOURCEFAILURE _ Failed to lock a specified resource. 
CDERR_LOADRESFAILURE Failed to load a specified resource. 
CDERR_LOADSTRFAILURE Failed to load a specified string. | 
CFERR_MAXLESSTHANMIN The size specified in SizeMax is less than the size in SizeMin. 
CFERR_NOFONT SS . No fonts exist. 

Flags 

uint32 Flags; 


Flags can be a combination of the following constants that control the appearance and 
functionality of the dialog box: 


CF_APPLY __ Enables the display and use of the Apply button. 
CF_ANSIONLY - Specifies that the ChooseFontDialog structure allows only the selection of 
_ fonts that use the ANSI character set. 
CF BOTH ~ Causes the dialog box to list both the available printer and screen fonts. 
CF_ EFFECTS Enables strikeout, underline, and color effects. | 
CF_FIXEDPITCHONLY Enables fixed-pitch fonts only. 
CF_FORCEFONTEXIST Indicates an error if the user selects a nonexistent font or style. . 
CF_INITTOLOGFONTSTRUCT Uses the LOGFONT structure at which LogFont points to initialize the 
| dialog controls. 
CF_LIMITSIZE Limits font selection to those between SizeMin and SizeMax. 
CF NOSIMULATIONS — Does not allow GDI font simulations. 
CF_PRINTERFONTS Causes the dialog box to list only the fonts supported by the printer 
that is associated with the device context. 
CF_SCALABLEONLY Allows only the selection of scalable fonts. 
CF_SCREENFONTS | Causes the dialog box to list only the system-supported screen fonts. 


CF_SHOWHELP Causes the dialog box to show the Help button. 
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Constant _ Meaning oS | ee | 
CF_TTONLY Enumerates and allows the selection of TrueType® fonts only. 
CF_USESTYLE Specifies that Style points to a buffer containing the style attributes used 
to initialize the selection of font styles. 
CF_WYSIWYG Allows only the selection of fonts available on both the printer and the 
screen. 
FontType 
uint16 FontType; 
Font type or name. 
LogFont 
LOGFONT LogFont; 
Attributes of the font. 
PointSize 
int PointSize; 


Point size of the font. 


SizeMax 

int SizeMax; 

Maximum size of the font. 
SizeMin 

int SizeMin; 

Minimum size of the font. 


See also T?ChooseFontDialog::Data 


Style 
char far* Style; 
Style of the font such as bold, italic, underline, or strikeout. 


A DC class derived from TWindowDC, TClientDC provides access to the client area 
owned by a window. 


See also 
TOleClientDC 


Public constructors 


Constructor 

TClientDC(HWND wnd); | 

Creates a TClientDC object with the given owned window. The data member Wnd is set 
to wnd. | 
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TClipboard class” 


See also TWindowDC::Wnd, TDC::TDC 


TClipboard encapsulates and manipulates clipboard data. You can open, close, empty, 
and paste data in a variety of data formats between the Clipboard and the open 
window. An object on the clipboard can exist in a variety of clipboard formats, which 
range from bitmaps to text. a ) 


Usually, the window is in charge of manipulating clipboard interactions between the 
window and the clipboard. It does this by responding to messages sent between the 

clipboard owner and the application. The following ObjectWindows event-handling 
functions encapsulate these clipboard messages: 


EvRenderFormat—Responds to a WM_RENDERFORMAT message sent to the clipboard 
owner if a specific clipboard format that an application has requested hasn't been 
rendered. After the clipboard owner renders the data in the requested format, it calls 
SetClipboardData to place the data on the clipboard. 


EvRenderAllFormats—Responds to a message sent to the clipboard owner if the 
clipboard owner has delayed rendering a clipboard format. After the clipboard owner 
renders data in all of possible formats, it calls SetClipboardData. 


The following example tests to see if there is a palette on the clipboard. If one exists, 
TClipboard retrieves the palette, realizes it, and then closes the clipboard. 


if (clipboard. IsClipboardFormatAvailable(CF_PALETTE)) { 
newPal = new TPalette(TPalette(clipboard)); // make a copy | 
UpdatePalette (true) ; 

} 


_ // TryDIB format first. 


if (clipboard. IsClipboardFormatAvailable(CF_DIB)) { 
newDib = new TDib(TDib(clipboard) ); // make a copy 
newBitmap = new TBitmap(*newDib, newPal); // newPal==0 is OK 
// try metafile 2nd | 
// | 7 | 
} else if (clipboard. IsClipboardFormatAvailable(CF_METAFILEPICT)) { 
if (!newPal) 
newPal = new TPalette( (HPALETTE) GetStockObject (DEFAULT_PALETTE) ) ; 
newBitmap = new TBitmap(TMetaFilePict (clipboard), *newPal, 
GetClientRect().Size()); 


// Gets a bitmap , keeps it, and sets up data on the clipboard. 
// 
delete Bitmap; 
Bitmap = newBitmap; 


if (!newDib) — | 
newDib = new TDib(*newBitmap, newPal); 
#endif 
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delete Dib; 
Dib = newDib; 


delete Palette; 
Palette = newPal ? newPal : new TPalette(*newDib) ; 
Palette->GetObject (Colors) ; 


PixelWidth = Dib->Width(); 
PixelHeight = Dib->Height (); 
AdjustScroller(); 
SetCaption("(Clipboard)"); 


clipboard.CloseClipboard() ; 


Public destructor 


Destructor 
~TClipboard(); 
Destroys the TClipboard object. 


Public data members 


DefaultProtocol 

static const char* DefaultProtocol; | 

Points to a string that specifies the name of the protocol the client needs. The default 
protocol is "StdFileEditing,” which is the name of the object linking and embedding 
protocol. 


Seealso TClipboard::QueryCreate 


Public member functions 


CloseClipboard 

void CloseClipboard() 

If the Clipboard is closed (IsOpen is false), closes the Clipboard. Closing the cited 
allows other applications to access the Clipboard. 


See also TClipboard::OpenClipboard 
CountClipboardFormats | 


int CountClipboardFormats() const; 
Returns a count of the number of types of data formats the Clipboard can use. 


Seealso TClipboard::RegisterClipboardFormat 
EmptyClipboard 
_ bool EmptyClipboard(); 


Clears the Clipboard and frees any handles to the Clipboard's data. Returns true if the 
Clipboard is empty, or false if an error occurs. 
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GetClipboard 
static TClipboard& GetClipboard() 
Returns a reference to the Clipboard object. 


GetClipboardData 

HANDLE GetClipboardData(uint format) const; 

Retrieves data from the Clipboard in the format specified by format. The following 
formats are supported: 


CF_BITMAP Data is in a bitmap format. 

CF_DIB Data is memory. 

CF_DIF Data is ina Data Interchange Format (DIF). 

CF DSPMETAFILEPICT . Data is ina metafile format. 

CF_DSPTEXT Data is in a text format. 

CF _ METAFILEPICT Data is in a metafile structure. 

CF_OEMTEXT Data is an array of text characters in OEM character set. 
-CF_OWNERDISPLAT Data is in a special format that the application must display. 

CF_PALETTE © Data is in a color palette format. 

CF_PENDATA Data is used for pen format. : 

CF_RIFF | Data is in Resource Interchange File Format (RIFF). 

CF_SYLK Data is in symbolic Link format (SYLK). 

CF_TEXT Data is stored as an array of text characters. 

CF _TIFF _ Data is in Tag Image File Format (TIFF). 

CF_WAVE Data is in a sound wave format. 


Seealso TClipboard::SetClipboardData 


GetClipboardFormatName 

int GetClipboardFormatName(uint format, char far* formatName, int maxCount) const; 

Retrieves the name of the registered format specified by format and copies the format to 
the buffer pointed to by formatName. maxCount specifies the maximum length of the 
name of the format. If the name is longer than maxCount, it is truncated. 


Seealso §TClipboard::CountClipboardFormats 


GetClipboardOwner 

HWND GetClipboardOwner() const; 

Retrieves the handle of the window that currently owns the Clipboard, otherwise 
returns NULL. | 3 


GetClipboardViewer 

HWND GetClipboardViewer() const; 

Retrieves the handle of the first window in the Clipboard-view chain. Returns NULL if 
there is no viewer. 


Seealso TClipboard::SetClipboardViewer 
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GetOpenClipboardWindow 

HWND GetOpenClipboardWindow() const; 

Retrieves the handle of the window that currently has the Clipboard open. If the 
Clipboard is not open, the return value is false. Once the Clipboard is opened, 
applications cannot modify the data. 


GetPriorityClipboardFormat 
int GetPriorityClipboardFormat(uint FAR * priorityList, int count) const; 


Returns the first Clipboard format in a list. priorityList points to an array that contains a 
list of the Clipboard formats arranged in order of priority. See GetClipboardData for the 


clipboard formats. 
Seealso TClipboard::GetClipboardData 


IsClipboardFormatAvailable 

bool IsClipboardFormatAvailable(uint format) const; 

Indicates if the format specified in format exists for use in the Clipboard. See 
GetClipBoardData for a description of clipboard data formats. 


The following code tests if the clipboard can support the specified formats: 


void 
TBmpViewWindow: :CePaste(TCommandEnabler& ce) 
{ 
TClipboard& clipboard = OpenClipboard|(); 
ce. Enable (. 
clipboard && ( 
clipboard. IsClipboardFormatAvailable(CF_METAFILEPICT) | | 
clipboard. IsClipboardFormatAvailable(CF_DIB) || 
clipboard. IsClipboardFormatAvailable(CF_BITMAP) 
); 
clipboard.CloseClipboard(); 


See also TClipboard::GetClipboardData 


OpenClipboard 

HWND GetOpenClipboardWindow() const; 

Retrieves the handle of the window that currently has the Clipboard open. If the 
Clipboard is not open, the return value is false. Once the Clipboard is opened, 
applications cannot modify the data. 


Seealso TClipboard::CloseClipboard 


bool 
operator bool() const; 
Checks handle. Should use IsOk instead. 


QueryCreate | 
bool QueryCreate(const char far* protocol = DefaultProtocol, OLEOPT_ RENDER renderopt = olerender_draw, 
OLECLIPFORMAT format = 0); 


QueryCreate determines if the object on the Clipboard supports the specified protocol 
and rendering options. DefaultProtocol points to a string specifying the name of the 
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protocol the client application needs to use. renderopt specifies the client application's 

display and printing preference for the Clipboard object. renderopt is set to 

olerender_draw, which tells the client library to obtain and manage the data presentation. 

format specifies the Clipboard format the client application requests. The macros 
_OLE_H or _INC_OLE must be defined before this function can be used. 


See also TClipboard: -QueryLink | 


QueryLink 

bool QueryLink(const char far* protocol = DefaultProtocol, OLEOPT_ RENDER renderopt = olerender draw, 
OLECLIPFORMAT format = 0); 

QueryLink determines if a client application can use the Clipboard data to produce a 

linked object that uses the specified protocol and rendering options. See 

TClipboard::QueryCreate for a description of the parameters. The macros OLE_H or 

_INC_OLE must be defined before this function can be used. 


Seealso TClipboard::QueryCreate 


RegisterClipboardFormat 

uint RegisterClipboardFormat(const char far* formatName) const; 

Registers a new Clipboard format. formatName points toa character string that identifies 
the new format. If the format can be registered, the return value indicates the registered 
format. If the format can't be registered, the return value is 0. Once the format is 
registered, it can be used as a valid format in which to render the data. 


See also. TClipboard: CountClipboardFormats, TClipboard: .GetClipboardFormatName 


SetClipboardData — 

HANDLE SetClipboardData(uint format, HANDLE handle); 

Sets a handle to the block of data at the location indicated by handle. format seats the 
format of the data block. The clipboard must have been opened before the data handle is 
set. format can be any one of the valid clipboard formats (for example, CF_BITMAP or 
CF_DIB). See GetClipboardData for a list of these formats. handle is a handle to the 
memory location where the data data is stored. If successful, the return value is a handle 
to the data; if an error occurs, the return value is 0. Before the window is updated with 
the clipboard data, the clipboard must be closed. 7 


See also ~-TClipboard: sa a 


SetClipboardViewer 

HWND SetClipboardViewer(HWND Wnd) const: 

Adds the window specified by Wnd to the chain of windows that 
WM_DRAWCLIPBOARD notifies whenever the contents of the Cupreae change. 


See also TClipboard: :GetClipboardViewer 
Protected data members 

IsOpen 

bool IsOpen; 

Returns true if the Clipboard is open. 
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Form 1 


Form 2 


TClipboardViewer Class 


TheClipboard 
static TClipboard TheClipboard; 
Holds the current clipboard. 


Protected constructor 


Protected constructor 
TClipboard(); 
Constructs a TClipboard object. 


Clipview.h 


T Clipboard Viewer is a mix-in class that registers a TClipboard Viewer as a Clipboard viewer 


when the user interface element is created, and removes itself from the Clipboard- 
viewer chain when it is destroyed. 


Protected data member 


HWndNext — 
HWND HWndNext; 
Specifies the next window in the Clipboard-viewer chain. 


Protected constructors 


Constructors 
TClipboardViewer(); 
Constructs a TClipboardViewer object. 


TClipboardViewer(HWND hWnd, TModule* module 2 0); 
Constructs a TClipboardViewer object with a handle (i4Wnd) to the windows that will 
receive notification when the Clipboard's contents are changed. 


Protected member functions 


DoChangeCBChain 

TEventStatus DoChangeCBChain(HWND hWndRemoved, HWND hWndNext); 

Tests to see if the Clipboard has changed and, if so, DoChangeCBChain forwards this 
message. 7 


DoDestroy 
TEventStatus DoDestroy(); 
Removes the window from the Clipboard-viewer chain. 


DoDrawClipboard 
TEventStatus DoDrawClipboard(); 
Handles EvDrawClipboard messages. 
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EvChangeCBChain 


~ void EvChangeCBChain(HWND hWndRemoved, HWND rWndNext 


Responds toa WM_CHANGECBCHAIN message. hWndRemoved is a handle to the 


_ window that's being removed. hWndNext is the window following the removed 


window. 


EvDestroy 

void EvDestroy/(); 

Responds to a WM_DESTROY message when a window is removed from the 
Clipboard-viewer chain. 


EvDrawClipboard 

void EvDrawClipboard(); 

Responds to a WM_DRAWCLIPBOARD message sent to the window in the Clipboard- 
viewer chain when the contents of the Clipboard change. 


SetupWindow 


— void SetupWindow(); 


Adds a window to the Clipboard-viewer chain. 
Seealso TWindow::SetupWindow 


Response table entries 


EV_WM_CHANGECBCHAIN | EvChangeCbChain 
EV_WM_DESTROY EvDestroy _ 
EV_WM_DRAWCLIPBOARD — EvDrawClipBoard 


TColor Class | | color.h 


Form 1 


Form 2 


TColor is a support class used in conjunction with the classes TPalette, TPaletteEntry, 
TRebQuad, and TRgbTriple to simplify all color operations. TColor has ten static data 
members representing the standard RGB COLORREF values, from Black to White. 
Constructors are provided to create TColor objects from COLORREF and RGB values, 
palette indexes, palette entries, and RGBQUAD and RGBTRIPLE values. 


See the entries for NBits and NColors for a description of TColor-related functions. 


Public constructors 


Constructors 
TColor(); 
The default constructor sets Value to 0. 


TColor(COLORREF value); 
Creates a TColor object with Value set to the given value. 
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Form 3 
Form 4 
Form 5 
Form 6 


Form 7 


Form 8 


Form 9 


TColor Class 


TColor(long value); 
Creates a TColor object with Value set to the value defined in COLORREF. 


TColor(int r, int g, int b); | 

Creates a TColor object with Value set to RGB(r,g,)). 

TColor(int r, int g, int b, int f); 

Creates a TColor object with Value set to RGB(r,g,b) with the flag byte formed from f. 


TColor(int index); 
Creates a TColor object with Value set to PALETTEINDEX(index). 


TColor(const PALETTEENTRY far& pe); 
Creates a TColor object with Value set to 
RGB(pe.peRed, pe.peGreen, pe.peBlue) 


TColor(const RGBQUAD faré& q); 

Creates a TColor object with Value set to 
RGB(g.rgbRed, g.rgbGreen, g.rgbBliue) 

TColor(const RGBTRIPLE far& t); 

Creates a TColor object with Value set to 
RGB(t.rgbtRed, t.rgbtGreen, t.rgbtBlue) 


See also COLORREF typedef, PALETTEENTRY struct, RGBQUAD struct, RGBTRIPLE 
struct, TColor::Value 


Public data members 


Black 
static const TColor Black; 
The static TColor object with fixed Value set by RGB(0, 0, 0). 


Gray 
static const TColor Gray; 
Contains the static TColor object with fixed Value set by RGB(128, 128, 128). 


LiBlue 
static const TColor LtBlue; | 
Contains the static TColor object with the fixed Value set by RGB(O, 0, 255). 


LtCyan 
static const TColor LtCyan; 
Contains the static TColor object with the fixed Value set by RGB(O, 255, 255). 


LtGray 
static const TColor LtGray; 
Contains the static TColor object with the fixed Value set by RGB(192, 192, 192). 


LtGreen 
static const TColor LtGreen;. | | 
Contains the static TColor object with the fixed Value set by RGB(O, 255, 0). 
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LtMagenta 
‘static const TColor LtMagenta; 
Contains the static TColor object with the fixed Value set Py RGB(255, 0, 255). 


LtRed 
static const TColor LtRed; 
Contains the static TColor object with the fixed Value set by RGB(255, 0, 0). 


LtYellow 
static const TColor LtYellow; 
Contains the static TColor object with the fixed Value set by RGB(255, 255, 0). 


- White 
static const TColor White; 
~ Contains the static PCO object with the fixed Value set by RGB(255, 255, 255). 


Public member functions 


Blue 
uint8 Blue() const; 
Returns the blue component of this color's Value. 


See also TColor::Red, TColor: :;Green, COLORREF poedet 


_ Flags 
uint8 Flags() const; 
Returns the peFlags value of this nee s Value. 


Seealso TPaletteEntry 
GetSysColor 


static TColor GetSysColor(int uiElement); 
(Presentation Manager only) Returns the color of the given uiElement. 


Green | 
uint8 Green() const; | 
Returns the green component of this color's Value. 


Seealso TColor::Red, TColor::Blue, COLORREF typedef 
operator == | 


bool operator ==(const TColoré& clrVal); 
Returns true if this color's Value equals clrValue; otherwise returns false. 


Seealso TColor::Value 


operator COLORREF() 
operator COLORREF() const; 
Type-conversion operator that returns Value. 


See also TColor::Value 
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Index 

int Index() const; 

Returns the index value corresponding to this color's Value by masking out the two 
upper bytes. Used when color is a palette index value. 


Seealso TColor::Value, COLORREF typedef 


Pallndex 

TColor Pallndex() const; 

Returns the palette index corresponding to this color's Value. The returned color has the 
high-order byte set to 1. 


Seealso TColor::Value, TColor::Index, COLORREF typedef 


PalRelative 

TColor PalRelative() const; 

Returns the palette-relative RGB corresponding to this color's Value. The returned color 
has the high-order byte set to 2. 


Seealso TColor::Value, TColor::Rgb, COLORREF typedef 


Red 
uint8 Red() const; 
Returns the red component of this color's Value. 


See also 
TColor::Blue, TColor::Green 


Rgb 

TColor Rgb() const; 

Returns the explicit RGB color corresponding to this color's Value by masking out the 
high-order byte. 

Seealso TColor::Value, COLORREF typedef 

SetSysColors | 

static bool SetSysColors(unsigned nelems, const int uiElementindices|], const TColor colors[]); 
(Presentation Manager only) Sets groups of UI element colors. nelems indicates the 
number of element colors to change (and the size of the array parameters, 


uiElementIndices indicates which elements to change, and colors indicates what color to 
change the corresponding element to. Returns true if successful. 


Protected data member 


Value 

COLORREF Value; 

The color value of this TColor object. Value can have three different forms, depending on 
the application: 


e Explicit values for RGB (red, green, blue) 


e An index into a logical color palette 
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_¢ A palette-relative RGB value 


See also COLORREF typedef 


TComboBox class combobox.h 


Form 1. 


Form 2 


You can use TComboBox to create a combo box or a combo box control in a parent 
TWindovw, or to facilitate communication between your application and the combo box 
controls of TDialog. TComboBox object: inherit most of their behavior from TListBox. This 
class is streamable. 


There are three types of combo boxes: ample drop down, and drop down list. These 
types are governed by the style constants CBS_SIMPLE, CBS_DROPDOWN, and 
CBS_DROPDOWNLIST. These constants, supplied to the constructor of a TComboBox, 
indicate the type of combo box element to create. | 


Public constructors 


Constructors 

TComboBox(TWindow* parent, int id, int x, int y, int w, int h, uint32 style, uint textLen, TModule* module = 0); 
Constructs a combo box object with the specified parent window (parent), control ID 
(Id), position (x, y) relative to the origin of the parent window's client area, width (w), 


height (A), style (style), and text length (textLen). 


Invokes the TListBox constructor with similar parameters. Then sets Attr. Style as 
follows: 


Attr.Style = WS_CHILD | WS_VISIBLE | WS_GROUP | WS_TABSTOP | CBS_SORT | CBS_AUTOHSCROLL | 
WS_VSCROLL | style; 


One of the following combo box style constants must be among the styles set in style: 
CBS_SIMPLE, CBS_DROPDOWN, CBS_DROPDOWNLIST, 
CBS_OWNERDRAWEIXED, or CBS_OWNERDRAWVARIABLE. 


TComboBox(TWindow* parent, int Resourceld, uint textLen = 0, TModule* module = 0); 
Constructs a default combo box with the given parent window control ID text length. 


Seealso T?ComboBox::GetTextLen, TListBox::TListBox 
Public data member 
TextLen 


uint TextLen; 
Contains the length of the text in the combo box's associated edit control. 


Public member functions 


AddString 
virtual int AddString(const char far* string); 
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Adds a string to an associated list part of a combo box. Returns the index of the string in 
the list. The first entry is at index zero. Returns a negative value if an error occurs. 


Clear 
void Clear(); 
Clears the text of the associated edit control. 


ClearList 
virtual void ClearList(); 
Clears out all associated entries in the associated list. 


DeleteString 

virtual int DeleteString(int index); 

Deletes the string at the passed index in the associated list part of a combo box. Returns 
a count of the entries remaining in the list or a negative value if an error occurs. 


DirectoryList 
virtual int DirectoryList(uint attrs, const char far* fileSpec); 
Fills the combo box with file names from a specified directory. 


FindString 

virtual int FindString(const char far* find, int indexStart) const; 

Searches for a match beginning at the passed Index. If a match is not found after the last 
string has been compared, the search continues from the beginning of the list until a 
match is found or until the list has been completely traversed. Returns the index of the 
first string in the associated list part of a combo box or a negative value if an error 
occurs. 


GetCount 

virtual int GetCount() const; 

Returns the number of entries in the associated list part of the combo box or a negative 
value if an error occurs. 


GetDroppedControlRect | 
void GetDroppedControlRect(TRect& Rect) const; 
For combo boxes, gets the screen coordinates of the dropped down list box. 


GetDroppedState 
bool GetDroppedState() const; 
For drop down combo boxes, determines if a list box is visible. 


GetEditSel 

int GetEditSel(int &startPos, int &endPos): | 

Returns the starting and ending positions of the text selected in the associated edit 
control. Returns CB_ERR if the combo box has no edit control. 


GetExtendedUI 

bool GetExtendedUI() const; 

Determines if the combo box has the extended user interface, which differs from the 
default user interface in the following ways: 


e Displays the list box if the user clicks the static text field. 
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e Displays the list box if the user presses the Down hese 
e Disables scrolling ; in the static text field if the item list is not visible. 
Returns true if the combo box has the extended user interface; otherwise returns false. 
See also TComboBox::SetExtendedUI | 


GetltemData a 
virtual uint32 GetltemData(int index) const; 7 
Returns the 32-bit value associated with the combo box's item. 


Seealso TListBox::GetltemData 


GetitemHeight 

int GetltemHeight(int index) const; 

Returns the height in pixels of the combo box's list items. If an error occurs, returns a 
negative value. 


See also TComboBox::GetltemData, TListBox::GetItemData 
GetSelindex 
virtual int GetSellndex() const; 

_ Returns the index of the list selection ora eeontive value if none exists. 


GetString 

virtual int GetString(char far* str, int index) const; 

Retrieves the contents of the string at the position sippleds in index and returns it in 
string. GetString returns the string length or a negative value if an error occurs. The 
buffer must be large enough for the string and the terminating zero. 


See also TListBox::GetString 


GetStringLen | 

virtual int GetStringLen(int index) const; 

Returns the string length (excluding the terminating zero) of the item at the position 
index supplied in index. Returns a negative value if an error occurs. — 


See also TListBox::GetStringLen 


GetText 
int GetText(char far* str, int maxChars) const; 
Retrieves the number of characters i in the edit or static portion of the combo box. 


GetTextLen 

int GetTextLen() const; 

Returns the text length (excluding the terminating zero) of the edit control or static 
portion of the combo box. 


HideList 
void HideList(); 
Hides the drop down list of a drop down or drop down list combo box. 


InsertString | 
virtual int InsertString(const char far* str, int index); 
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Inserts a string in the associated list part of a combo box at the position supplied in 
Index. Returns the index of the string in the list or a negative value if an error occurs. 


Seealso TListBox::InsertString 


SetEditSel 

int SetEditSel(int startPos, int endPos); 

Selects characters that are between startPos and endPos in the edit control of the combo 
box. Returns CB_ERR if the combo box does not have an edit control. 


SetExtendedUl 
int SetExtendedUI(bool extended); 
If the combo box has the extended user interface, sets the extended user interface. 


See also TComboBox::GetExtendedUI 


SetitemData 

virtual int SetltemData(int index, uint32 data); 

Sets the 32-bit value associated with the TComboBox’s item. If an error occurs, returns a 
negative value. 


SetitemHeight 

int SetitemHeight(int index, int height); 

Sets the height of the list items or the edit control portion in a combo box. If the index or 
height is invalid, returns a negative value. 


See also TComboBox::GetltemHeight 


SetSellndex 

virtual int SetSellndex(int index); 

Selects a string of characters in a combo box. index specifies the index of the string of 
characters in the list box to select. If the index is 0, the first line in the list box is selected. 
If the index is —1, the current selection is removed. If an error occurs, a negative value is 
returned. 


See also TCombobocCacetindex 


SetSelString 

virtual int SetSelString(const char far* findStr, int indexStart); 

Selects a string of characters in the associated list box and sets the contents of the 
associated edit control to the supplied string. : 


SetText 

void SetText(const char far* string); 

Selects the first string in the associated list box that begins with the supplied string. If 
there is no match, SetText sets the contents of the associated edit control to the supplied 
string and selects it. 


ShowList 
void ShowList(); 
Shows the list of a drop down or drop down list combo box. 


void ShowList(bool show): 
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Shows or hides the drop down or drop down list combo box depending on the value of - 
show. If show is true, shows the list; if show is false, hides the list. 


See also TComboBox::HideList 


Transfer 

uint Transfer(void* buffer, TTransferDirection direction); | 

Transfers the items and selection of the combo box to or from a transfer buffer if 
tdSetData or tdGetData, respectively, is passed as the direction. buffer is expected to point 
to a TComboBoxData structure. 


Transfer returns the size of a pointer to a TComboBoxData. To retrieve the size without 
transferring data, your application must pass tdSizeData as the direction. 


You must use a pointer in your transfer buffer to these structures. You cannot embed 
copies of the structures in your transfer buffer, and you cannot use these structures as 
transfer buffers. 


See also TComboBoxData, TWindow::Transfer, Window::SetupWindow 


Protected member functions 


GetClassName 
virtual char far* GetClassName(); 
Returns the name of TComboBox’s registration class, "ComboBox." 


SetupWindow 

void SetupWindow(); 

Sets up the window and limits the amount of text the user can enter in the combo box's 
edit control to the value of TextLen minus 1. 


TComboBoxData class combobox.h 


An interface object that represents a transfer buffer for a TComboBox. 


Public constructor and destructor 


Constructor 

TComboBoxData(); 

Constructs a TComboBoxData object, initializes Strings and ItemDatas to Empey ara 
and initializes Selection and SelIndex to 0. 


Destructor 
~TComboBoxData(); . 
Deletes Strings, ItemDatas, and Selection. 
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Public member functions 


AddString 

void AddString(const char *str, bool isSelected = false); 

Adds the specified string to the array of Strings. If IsSelected is true, AddString deletes 
Selection and copies string into Selection. 


AddStringltem 

void AddStringltem(const char* str, uint32 itemData, bool isSelected = false); 

Calls AddItemData to add the item data to the ItemDatas array, and calls AddString to add 
a string to the array of Strings. 


Clear 
void Clear(); 
Flushes the Strings and ItemDatas members. Resets the index and selected string values. 


GetlitemDatas 
TDwordArray& GetltemDatas(); 
Returns the array of DWORDs to transfer to or from a combo box's associated list box. 


GetSelCount 
int GetSelCount() const; 
Returns the number of items selected, either 0 or 1. 


GetSelection 

string& GetSelection(); 

Returns the currently selected string (the Selection data member) to transfer to or from a 
combo box. 


GetSelindex 
int GetSellndex(); 
Returns the index (the SelIndex data member) of the selected item in the strings array. 


GetSelString 

void GetSelString(char far* buffer, int bufferSize) const; 

Copies the selected string into a buffer of the specified size. bufferSize includes the 
terminating 0. | 


GetSelStringLength 
int GetSelStringLength() const; 
Returns length of the currently selected string excluding the terminating 0. 


GetStrings 

TStringArray& GetStrings(); | 

Returns the array of strings (the Strings data member) to transfer to or from a combo 
box's associated list box. 


ResetSelections 
void ResetSelections(); 
Resets the index of the selected item and the currently selected string. 
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void Select(int index); 
Selects the item at the given index. 


SelectString 

void SelectString(const char far* str); 

Selects the selection string (str) and makes the matching String entry (if o7 one oe) as 
selected. 


Protected data members 


ItemDatas 
TDwordArray ItemDatas; 
Array of DWORDs to cenetes to or from a combo box's associated list box. 


Selection 
string Selection; 
The currently selected string to transfer to or from a combo box. 


Selindex 
int Sellndex; 
Index of the selected item in the strings array. 


Strings 
TStringArray Strings; 
Array of class ne to transfer to or from a combo box's aeecaia list box. 


TCommandEnabler class _ ~— window.h 


An abstract base class used for automatic enabling and disabling of commands, 
TCommandEnabler is a class from which you can derive other classes, each one having its 
“own command enabler. For example, TButtonGadgetEnabler is a derived class that's a 
command enabler for button gadgets, and TMenultemEnabler is a derived class that's a 
command enabler for menu items. Although your derived classes are likely to use only 
the functions Enable, SetCheck, and GetHandled, all of TCommandEnabler’s functions are 
described so that you can better understand how ObjectWindows uses command — 
processing. The following paragraphs explain the dynamics of command processing. 


Handling command messages | 

Commands are messages of the windows WM_COMMAND type that have associated 
command identifiers (for example, CM_FILEMENU). When the user selects an item 
from a menu or a toolbar, when a control sends a notification message to its parent 
window, or when an accelerator keystroke i is translated, a WM_COMMAND message is 
sent to a window. 
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Responding to command messages 

A command is handled differently depending on which type of command a window 
receives. Menu items and accelerator commands are handled by adding a command 
entry to a message response table using the EV_ COMMAND macro. The entry requires 
two arguments: 


e A command identifier (for example, CM_LISTUNDO) 
e A member function (for example, CMEditUndo) 


Child ID notifications, messages that a child window sends to its parent window, are 
handling by using one of the notification macros defined in the header file windowev.h. 


It is also possible to handle a child ID notification at the child window by adding an 
entry to the child's message response table using the EV_NOTIFY_AT_CHILD macro. 
This entry requires the following arguments: 


e¢ A notification message (for example, LBN_DBLCLK) 
¢ A member function (for example, CmEditItem) 


TWindow command processing 
One of the classes designed to handle command processing, TWindow performs basic 
command processing according to these steps: 


1 The member function WindowProc calls the virtual member function EvCommand. 


2 EvCommand checks to see if the window has requested handling the command by 
looking up the command in the message response table. 


3 If the window has requested handling the command identifier by using the 
EV_COMMAND macro, the command is dispatched. 


~TWindow also handles Child ID notifications at the child window level. 


TFrameWindow command processing 

TFrameWindow provides specialized command processing by overriding its member 
function EvCommand and sending the command down the command chain (that is, the 
chain of windows from the focus window back up to the frame itself, the original 
receiver of the command message). 


If no window in the command chain handles the command, TFrameWindow delegates 
the command to the application object . Although this last step is theoretically 
performed by the frame window, it is actually done by TWindow’s member function, 
DefaultProcessing. 


Invoking EvCommand 

When TFrameWindow sends a command down the command chain, it doesn't directly 
dispatch the command; instead, it invokes the window's EvCommand member 
function.This procedure gives the windows in the command chain the flexibility to 
handle a command by overriding the member function EvCommand instead of being 
limited to handling only the commands requested by the EV_ COMMAND macro. 
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Handling command enable messages 

Most applications expend considerable energy updating menu items and tool bar 
buttons to provide the necessary feedback indicating that a command has been enabled. 
In order to simplify this procedure, ObjectWindows lets the event handler that's going 
to handle the command make the decision about whether or not to enable or disable a 
command. 


Although the WM_COMMAND. ENABLE message is sent down the same command 
chain as the WM_COMMAND event; exactly when the WM_COMMAND_ENABLE 
message is sent depends on the type of command enabling that needs to be processed. 


Command enabling for menu items 

TFrameWindow performs this type of command enabling when it receives a 
WM_INITMENUPOPUP message. It sends this message before a menu list appears. 
ObjectWindows then identifies the menu commands using the command IDs and sends 
requests for the commands to be enabled. 


Note that because Object Windows actively maintains toolbars and menu items, any 
changes made to the variables involved in the command enabling functions are 
implemented ae and not just when a window is activated. 


Command enabling for toolbar buttons 

The type of command enabling is performed during idle processing (in the IdleAction | 
_ function). See the diagram following the description of TWindow::DefaultProcessing for a 

graphical illustration of this process. 


Creating specialized command enablers 

‘Associated with the WM_COMMAND._ ENABLE message is an ae of the 
TCommandEnabler type. This family of command enablers includes specialized 
command enablers for menu items and toolbar buttons. 


As you can see from TCommandEnable’s class declaration, you can do considerably more 
than simply enable or disable a command using the command enabler. For example, 
you have the ability to change the text associated with the command as well as the state 
of the command. 


Using the EV COMMAND ENABLE macro 

You can use the EV.COMMAND_ENABLE macro to handle 
WM_COMMAND_ENABLE messages. Just as you do with the EV_COMMAND 
macro, you specify the command identifier that you want to handle and the member 
function you want to invoke to handle the message. 


Automatically enabling and disabling commands 

ObjectWindows simplifies enabling and disabling of commands by automatically 
disabling commands for which there are no associated handlers. TFrameWindow's 
member function EvCommandEnable performs this operation, which involves 
completing a two pass algorithm. 
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1 The first pass sends a WM_COMMAND_ENABLE message down the command 
chain giving each window an explicit opportunity to do the command enabling. 


2 Ifno window handles the command enabling request, then ObjectWindows checks 
to see whether any windows in the command chain are going to handle the | 
command through any associated EV_COMMAND entries in their response tables. If 
there is a command handler in one of the response tables, then the command is 
enabled; otherwise it is disabled. 


Because of this implicit command enabling or disabling, you do not need to (and 
actually should not) do explicit command enabling unless you want to change the 
command text, change the command state, or conditionally enable or disable the 
command. 


If you handle commands indirectly by overriding the member function EvCommand _ 
instead of using the EV_COMMAND macro to add a response table entry, then 
ObjectWindows will not be aware that you are handling the command. Consequently, 
the command may be automatically disabled. Should this occur, the appropriate action 
to take is to also override the member function EvCommandEnable and explicitly enable 
the command. | 


Public constructor 


Constructor 

TCommandEnabler(uint id, HWND hWndReceiver = 0); 

Constructs the TCommandEnable object with the specified command ID. Sets the 
message responder (iWndReceiver) to zero. 


Type definitions 


CheckState 

enum CheckState{Unchecked, Checked, Indeterminate}; 

Enumerates the values for the check state of the command sender. This state applies to 
buttons, such as those used for tool bars or to control bar gadgets. 


Public data members 
Id 


const uint Id; 
Command ID for the enabled command. 


Public member functions 
Enable 


virtual void Enable(bool enable = true); 
Enables or disables the command sender. When Enable is called, it sets the Handled flag. 
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GetHandled 

bool GetHandled(); 

Returns Handled, a flag value that shows if this command enabler has been handled, in. 
which case Handled is true. 


IsReceiver 

bool IsReceiver(HWND hReceiver); . 
~ Returns true if receiver is the same as the message responder originally: set up in the 

constructor. 


SetCheck © 

virtual void SetCheck(int check) = 0; 

Changes the check state of the command sender to either unchecked, checked, or 
indeterminate. This state applies to buttons, such as those used for toolbars or to control 
bar gadgets. 


SetText 

virtual void SetText(const char far* text) = 0; 

Changes the text associated with a command sender. This applies, for example, to text 
associated with a menu item or text ona button. 


Protected data members 


Handled 
bool Handled; 
Is true if the command enabler has been handled. 


HWndReceiver 
const HWND HWndReceiver; 
The message responder (the window) that receives the command. 


TCommonDialog class _ _commdiath 


Derived from TDialog, TCommonDialog is the abstract base class for TCommonDialog 
objects. It provides the basic functionality for creating dialog boxes using the common 
dialog DLL. The Chis wandons classes that inherit this common dialog functionality 
include 


TChooseColorDialog—a modal dialog box that lets a user ee colors for an application 
TChooseFontDialog—a modal dialog box that lets a user select fonts for an application 
| TReplaceDialog—a modeless dialog box that lets a user specify a text selection to replace 
TFindDialog—a modeless dialog box that lets a user specify a text selection to find 
| TFileOpenDialog—a modal dialog box that lets a user specify a file to open 
TFileSaveDialog—a modal dialog box that lets a user specify a file to save 


TPrintDialog—a modal dialog box that lets a user specify printer options 
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Each common dialog class uses a nested class, TData, that stores the attributes and user- 
specified data. For example, the TChooseColorDialog::T Data class stores the color 
attributes the user selects in response to a prompt in a common dialog box. In fact, to 
create a common dialog box, you construct a TData object first, then fill in the data 
members of the TData object before you even construct the common dialog box object. 
Finally, you either execute a modal dialog box or create a modeless dialog box. 


Public constructor 


Constructor 

TCommonDialog(TWindow* parent, const char far* title = 0, TModule* module = 0); 

Invokes a TWindow constructor, passing the parent window parent and constructs a 
common dialog box which you can modify to suit your specifications. You can indicate 
the module ID (title) and window caption (title), which otherwise default to 0. 


Public member functions 


DoCreate 
HWND DoCreate(); 
Called by Create, DoCreate creates a modeless dialog box. It returns 0 if unsuccessful. 


Seealso TDialog::Create 


DoExecute 

int DoExecute(); 

Called by Execute, DoExecute executes a modal dialog box. If the dialog box execution is 
canceled or unsuccessful, DoExecute returns IDCANCEL. 


Seealso TDialog::Execute 


Protected data member 


CDTitle 
const char far* CDTitle; 
CDTitle stores the optional caption displayed in the common dialog box. 


Seealso TDialog::SetCaption 


Protected member functions 


CmHelp 
void CmHelp(); 
Default handler for the pshHelp push button (the Help button in the dialog box). 


CmOkCancel 

void CmOkCancel(); 

Responds to a click on the dialog box's OK or Cancel button by calling DefaultProcessing 
to let the common dialog DLL process the command. 
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Seealso TDialog: encima a, TDialog: :CmOk 


—EvClose 
void EvClose(); 
Responds to a WM_CLOSE message by calling Palit ene to let the common 
dialog DLL process the command. 


Seealso TDialog::EvClose 
SetupWindow | 


_ void SetupWindow(); 
Assigns the caption of the dialog box to CDTitle if CDTitle is nonzero. 


Seealso TDialog::SetupWindow 


Response table entries 


EV_COMMAND(IDCANCEL, CmOkCancel) CmOkCancel 


EV_COMMAND(IDOK, CmOkCancel) CmOkCancel 
EV_WM_CLOSE EvClose 
EV_WM_CTLCOLOR — EvCtlColor 


TCondFunc typedef window.h | 


typedef bool (*TCondFunc) (TWindow *win, void *param); 
Defines a member function type used by TWindow’s function FirstThat. 


See also TWindow::FirstThat 


typedef bool (TWindow_TCondMemFunc) ‘win, void *param); 
Defines a member function type used by TWindow’s function FirstThat. 


See also TWindow::FirstThat 
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TControlBar class controlb.h 


Derived from TGadgetWindow, FControlBar implements a control bar that provides 
mnemonic access for its button gadgets. The sample MDIFILE.CPP ObjectWindows 
oe on. — distribution disk alee the following example of a control bar. 


Ty 

SK 
BS 
aL 


Button gadgets Control bar 


To construct, build, and insert a control bar into a frame window, you can first define 
the following response table: 


DEFINE_RESPONSE_TABLE1 (TMDIFileApp, TApplication 
EV_COMMAND(CM_FILENEW, CmFileNew), 
EV_COMMAND(CM_FILEOPEN, CmFileOpen) , 
EV_COMMAND (CM_SAVESTATE, CmSaveState), 
EV_COMMAND (CM_RESTORESTATE, CmRestoreState), 

END RESPONSE TABLE; 


Next, add statements that will construct a main window and load its menu, accelerator 
table, and icon. Then, to construct, build and insert a control bar into the frame window, 
insert these statements: 


TControlBar* cb = new TControlBar (frame) ; 

cb->Insert (*new TButtonGadget (CM_FILENEW, CM_FILENEW) ); 
cb->Insert (*new TButtonGadget (CM_FILEOPEN, CM_FILEOPEN) }; 
cb->Insert (*new TButtonGadget (CM_FILESAVE, CM_FILESAVE) }; 
cb->Insert (*new TSeparatorGadget (6)); 

cb->Insert (*new TButtonGadget (CM_EDITCUT, CM_EDITCUT) }; 
neta tall TButtonGadget (CM_EDITCOPY, CM_EDITCOPY)); 
cb->Insert (*new TButtonGadget (CM_EDITPASTE, CM_EDITPASTE) ) ; 
cb->Insert (*new TSeparatorGadget (6) ); 

ee TButtonGadget (CM_EDITUNDO, CM _EDITUNDO) ); 
frame->Insert (*cb, TDecoratedFrame: :Top); 


Public constructor 


Constructor 
TControlBar(TWindow* parent = 0, TTileDirection direction = Horizontal, TFont* font = new TGadgetWindowFont, 
TModule* module = 0); 


Constructs a TControlBar interface object with the specified direction (either horizontal 
or vertical) and window font. 


Public member function 


PreProcessMsg 
bool PreProcessMsg(MSG& msg); 
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Preprocesses messages. Because PreProcessMsg does not translate any accelerator keys 
for TControlBar, it returns false. 


Protected member function 


PositionGadget 

void PositionGadget(TGadget* previous, TGadget* next, TPoint& p); 

Gets the border style, determines the direction of the gadget, and positions the button. 
gadget on either a horizontal or vertical border if any overlapping is required. | 


TControlGadget serves as a surrogate for TControl so that you can place TControl objects 
such as edit controls, buttons, sliders, gauges, or third-party controls, into a gadget 
window. If necessary, TControlGadget sets a parent window and creates the control 
gadget. See [Gadget for more information about gadget objects. _ 


Public constructor and destructor 


Constructor 
TControlGadget(TWindowé control, TBorderStyle = None); 
Creates a TControlGadget object associated an the specified TControl window. 


Destructor 
~TControlGadget(); 
eneye a TControlGadget object and removes it econ the seocaied window. 


Protected data member 


Control 
TWindow* Control; 
Points to the control window that is managed by this TControlGadget. 


Protected member functions 


GetDesiredSize 

void GetDesiredSize(TSize& size); 

Calls TGadget::GetDesiredSize and passes the size of the control gadget. Use 
GetDesiredSize to find the size the control gadget needs to be in order to accommodate 
the borders and margins as well as the highest and widest control gadget. 


Seealso TGadget::GetDesiredSize 


GetinnerRect © 
void GetinnerRect(TRect&); 
a the area of the control gadget's nee excluding the borders and margins. 
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Inserted 

void Inserted(); 

Called when the control gadget is inserted in the parent window. Displays the window 
in its current size and position. 


Invalidate 

void Invalidate(bool erase = true); 

Used to invalidate the active (usually nonborder) portion of the control gadget, 
Invalidate calls InvalidateRect and passes the boundary width and height of the area to 
erase. 


InvalidateRect 
void InvalidateRect(const TRect&, bool erase = true); 
Invalidates the control gadget rectangle in the parent window. 


Removed 
void Removed(); 
Called when the control gadget is removed from the parent window. 


SetBounds 

void SetBounds(TRect& rect); 

Calls TGadget::SetBounds and passes the dimensions of the control gadget's rectangle. 
SetBounds informs the control gadget of a change in its bounding rectangle. 


Seealso TGadget::SetBounds 


Update 

void Update(); 

Updates the client area of the specified window by immediately sending a WM_PAINT 
message. 


Response table entries 


The TControlGadget class has no response table entries. 


TControl class | | control.h 


Form 1 


TControl unifies its derived control classes, such as TScrollBar, TControlGadget, and 
TButton. Control objects of derived classes are used to represent control interface 
elements. A control object must be used to create a control in a parent TWindow or a 
derived window. A control object can be used to facilitate communication between your 
application and the controls of a TDialog. TControl is a streamable class. 


Public constructors 


Constructors 
TControl(TWindow* parent, int id, const char far’ title, int x, int y, int w, int h, TModule* module = 0); 
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Form 2 


Invokes TWindow’s constructor, passing it parent (parent window), title (caption text), 
and module. Sets the control attributes using the supplied library ID (Id), position (x, y) 
relative to the origin of the parent window's client area, width (w), and height (/) 
parameters. It sets the control style to WS_CHILD | WS_VISIBLE | WS GROUP | 


-WS_TABSTOP. 


TControl(TWindow* parent, int resourceld, TModule* module = 0); 

Constructs an object to be associated with an interface control of a TDialog. Invokes the 
TWindow constructor then enables the data transfer mechanism by calling 
EnableTransfer. 


The resourceld parameter must correspond to a control ee resource that you 
define. 


Seealso TWindow::TWindow, TWindow::EnableTransfer 


Protected member functions 


Compareltem 
virtual int Compareltem (COMPAREITEMSTRUCT far& comparelnfo); 
Also used with owner-draw buttons and list boxes, Compareltem connate. two items. 


_ The derived class auEEUS the compare logic. 


See also 
COMPAREITEMSTRUCT struct 


Deleteltem 

virtual void Deletelttem (DELETEITEMSTRUCT far& deletelnfo); 

DeleteItem is used with owner-draw buttons and list boxes. In such cases, the derived 
class supplies the delete logic. 


See also DELETEITEMSTRUCT struct 


Drawitem 

virtual void Drawltem(DRAWITEMSTRUCT far& drawlnfo); 

Drawltem responds to a message forwarded to a drawable control by TWindow when the 
control needs to be drawn. TControl::Drawltem calls ODADrawEntire if the entire control 
needs to be drawn, calls ODASelect if the selection state of the control has changed, or 
calls ODAFocus if the focus has been shifted to or from the control. 


Seealso TControl::;ODADrawEntire, TControl::ODASelect, TControl::ODA Focus, 
DRAWITEMSTRUCT struct 


EvCompareltem 
LRESULT EvCompareltem(uint ctrlld, COMPAREITEMSTRUCT far& comp); 
Handles a WM_COMPAREITEM message for owner-draw controls. 


See also COMPAREITEMSTRUCT struct 


-EvDeleteltem 


void EvDeleteltem(uint ctrild, DELETEITEMSTRUCT far& del) 


Handles a WM_DELETEITEM message for owner-draw controls. 
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Seealso DELETEITEMSTRUCT struct 


EvDrawlitem 
void EvDrawltem(uint ctrild, DRAWITEMSTRUCT far& draw); 
Handles a WM_DRAWITEM message. 


Seealso DRAWITEMSTRUCT struct 


EvMeasureltem 
void EvMeasureltem(uint ctrild, MEASUREITEMSTRUCT far& meas); 
Handles a WM_MEASUREITEM message. 


See also MEASUREITEMSTRUCT struct 


EvPaint 

void EvPaint(); 

If the control has a predefined class, EvPaint calls TWindow::DefaultProcesing for 
painting. Otherwise, it calls TWindow::EvPaint. 


Seealso TWindow::DefaultProcessing 


Measureltem 

virtual void Measureltem (MEASUREITEMSTRUCT far& measurelnfo); 

Used by owner-drawn controls to set the dimensions of the specified item. For list boxes 
and control boxes, this function applies to specific items; for other owner-drawn 
controls, this function is used to set the total size of the control. 


See also MEASUREITEMSTRUCT struct 


ODADrawEntire 

virtual void ODADrawEntire(DRAWITEMSTRUCT far& drawinfo); 

Responds to a notification message sent to a drawable control when the control needs to 
be drawn. ODADrawEntire can be redefined by a drawable control to specify the 
manner in which it is to be drawn. | 


Seealso TControl::Drawltem, DRAWITEMSTRUCT struct 


ODAFocus 

virtual void ODAFocus(DRAWITEMSTRUCT far& drawinfo); 

Responds to a notification sent to a drawable control when the focus has shifted to or 
from the control. ODAFocus can be redefined by a drawable control to specify the 
manner in which it is to be drawn when losing or gaining the focus. 


See also TControl::Drawltem, DRAWITEMSTRUCT struct 


ODASelect 

virtual void ODASelect(DRAWITEMSTRUCT far& drawinfo); 

Responds to a notification sent to a drawable control when the selection state of the 
control changes. ODASelect can be redefined by a drawable control to specify the 
manner in which it is drawn when its selection state changes. 


See also TControl::Drawltem, DRAWITEMSTRUCT struct 
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Form 1 


Form 2 


Response table entries 


EV_WM_PAINT EvPaint 
EV_WM_COMPAREITEM EvCompareltem 
EV_WM_DELETEITEM EvDeleteItem 
EV_WM_DRAWITEM EvDrawltem 
EV_WM_MEASUREITEM EvMeasureltem 
TCreatedDC class | | | deh 


An abstract TDC class, TCreatedDC serves as the base for DCs that are created and 
deleted. 


See TDC for more information about DC objects. 


Public constructors and destructor 


Constructors | 

TCreatedDC(const char far* driver, const char far* aeyice, const char far" output, 

const DEVMODE far’ initData=0); 

Creates a DC object for the device spades by driver (driver name), device (device name), 
and output (the name of the file or device [port] for the physical output medium). The 


_ optional initData argument provides a DEVMODE structure containing device-specific 


initialization data for this DC. initData must be 0 (the default) if the device is to use any 


default initializations specified by the user. 


TCreatedDC(HDC handle TAutoDelete autoDelete); 
Creates a DC object using an existing DC. 


Destructor 

~TCreatedDC(); 

Calls RestoreObjects clears any nonzero OrgXXX data members. If ShouldDelete is true 
the destructor deletes this DC. 


Seealso enum TDC::TAutoDelete, TDC: pees TDC::ShouldDelete, 
DEVMODE struct 


Protected constructor 


Constructor 

TCreatedDC(); 

Creates a device context for the given device. DC objects can be constructed either by 
borrowing an existing HDC handle or by supplying device and driver information. 
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TCursor class gdiobjec.h 


Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


Form 6 


TCursor, derived from TGdiBase, represents the GDI cursor object class. TCursor 
constructors can create cursors from a resource or from explicit information. Because 
cursors are not real GDI objects, the TCursor destructor overrides the base destructor, 
~TGdiBase. 


Public constructors and destructor 


Constructors | 

TCursor(HCURSOR handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TCursor object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 


TCursor(HINSTANCE instance, const TCursor& cursor); 
Creates a copy of the given cursor object. The 32-bit version (for compiling a Win32 
application) uses Copylcon() and does a cast to get to HICON. 


TCursor(HINSTANCE instance, Resid resid); 
Constructs a cursor object from the specified resource ID. 


TCursor(HINSTANCE instance, const TPoint& hotSpot, const TSize& size, void far* andBits, void far* xorBits); 
Constructs a TCursor object of the specified size at the specified point. 


TCursor(const void* resBits, uint32 resSize); 
32 bit only. Constructs a TCursor object from the specified resource. 


TCursor(const ICONINFO* iconInfo); 
32 bit only. Creates a TCursor object from the specified ICONINFO structure 
information. 


Destructor 
~TCursor(); 
Destroys a TCursor object. 


Seealso ~TGdiObject, TGdiObject::Handle, TGdiObject::ShouldDelete, TPoint, TSize, 
ICONINEO struct 


Public member function 


GeticonInfo 

bool GetlconInfo(ICONINFO* iconInfo) const; 

32-bit only. Retrieves information about this icon and copies it in the given ICONINFO 
structure. Returns true if the call is successful; otherwise returns false. 


See also ICONINFO struct 
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Operators 


operator HCURSOR() 


operator HCURSOR() const; 
An inline typecasting operator. Converts this cursor's Handle to type HCURSOR os 
data EE representing the handle to a cursor resource). 


operator == 
bool operator ==(const TCursor& other) const; 


Returns true if this cursor equals other; otherwise returns false. 


TDC class - | | de.h 


-TDCis the root class for GDI DC wrappers. Each TDC object inherits a Handle from 
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TGdiBase and casts that handle to an HDC using the HDC operator. Win API functions 
that take an HDC argument can therefore be called by a corresponding TDC member 
function without this explicit handle argument. 


DC objects can be created directly with TDC constructors, or via the constructors of 
specialized subclasses (such as TWindowDC, TMemoryDC, TMetaFileDC, TDibDC, and 
TPrintDC) to get specific behavior. DC objects can be constructed with an already 
existing and borrowed HDC handle or from scratch by supplying device driver 
information, as with ::CreateDC. The class TCreateDC takes over much of the creation 
and deletion work from TDC. 


TDC has four handles as protected data members: OrgBrush, OrgPen, OrgFont, and 
OrgPalette. These handles keep track of the stock GDI objects selected into each DC. As 
new GDI objects are selected with SelectObject or SelectPalette, these data members store 
the previous objects. The latter can be restored individually with RestoreBrush, 
RestorePen, and so on, or they can all be restored with RestoreObjects. When a TDC object 
is destroyed (via ~[TDC::TDC), all the originally selected objects are restored. The data 
member TDC::ShouldDelete controls the deletion of the TDC object. 


Public constructor and destructor 


Constructor 

TDC(HDC handle); 

Creates a DC object "borrowing" the handle of an existing DC. The Handle data member 
is set to the given handle argument. 


Destructor 
virtual ~TDC(); 
Calls RestoreObjects. 


See also TCreatedDC, TDC: RestoreObjects, TDC: ‘ShouldDelete 


tWindows Reference Guide 


TDC class 


Public member functions 


AngleArc 

bool AngleArc(int x, int y, uint32 radius, float startAngle, float sweepAngle); 

bool AngleArc(const TPoint& center, uint32 radius, float startAngle, float sweepAngle); 

32-bit only. Draws a line segment and an arc on this DC using the currently selected pen 
object. The line is drawn from the current position to the beginning of the arc. The arc is 
that part of the circle (with the center at logical coordinates (x, y) and positive radius, 
radius) starting at startAngle and ending at (startAngle + sweepAngle). Both angles are 
measured in degrees, counterclockwise from the x-axis (the default arc direction). The 
arc might appear to be elliptical, depending on the current transformation and mapping 
mode. AngleArc returns true if the figure is drawn successfully; otherwise, it returns 
false. If successful, the current position is moved to the end point of the arc. 


See also TDC::Arc, TPoint class 


Arc 

bool Arc(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4); 

bool Arc(const TRect& r, const TPoint& start, const TPoint& end); 

Draws an elliptical arc on this DC using the currently selected pen object. The center of 
the arc is the center of the bounding rectangle, specified either by (x1, y1)/(x2, y2) or by 
the rectangle r. The starting /ending points of the arc are specified either by (x3, y3)/(x4, 
y4) or by the points start and end. All points are specified in logical coordinates. Arc 
returns true if the arc is drawn successfully; otherwise, it returns false. The current 
position is neither used nor altered by this call. The drawing direction default is 
counterclockwise. 


See also TDC::AngleArc, TPoint, TRect 


BeginPath 

bool BeginPath(); 

32-bit only. Opens a new path bracket for this DC and discards any previous paths from 
this DC. Once a path bracket is open, an application can start calling draw functions on 
this DC to define the points that lie within that path. The draw functions that define 
points in a path are the following TDC members: AngleArc, Arc, Chord, CloseFigure, 
Ellipse, ExtTextOut, LineTo, MoveToEx, Pie, PolyBezier, PolyBezierTo, PolyDraw, Polygon, 
Polyline, PolylineTo, PolyPolygon, PolyPolyline, Rectangle, RoundRect, and TextOut. 


A path bracket can be closed by calling TDC::EndPath. 
BeginPath returns true if the call is successful; otherwise, it returns false. 


Seealso TDC::FillPath, TDC::EndPath, TDC::PathToRegion, TDC::StrokePath, 
TDC::StrokeandFillPath, TDC::WidenPath 


BitBit 

bool BitBit(int dstX, int dstY, int w, inth, const TDC& srcDC, int srcX, int srcY, uint32 rop=SRCCOPY); 

bool BitBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, uint82 rop=SRCCOPY); 

Performs a bit-block transfer from srcDc (the given source DC) to this DC (the 
destination DC). Color bits are copied from a source rectangle to a destination rectangle. 
The location of the source rectangle is specified either by its upper left-corner logical 
coordinates (srcX, srcY), or by the TPoint object, src. The destination rectangle can be | 
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specified ane is its upper left-corner logical coordinates (dstX, ast), width w, and 
height h, or by the TRect object, dst. The destination rectangle has the same width and 
height as the source. The rop argument specifies the raster operation used to combine 
the color data for each pixel: See TDC::MaskBit for a detailed list of rop codes. 


When recording an enhanced metafile, an error occurs if the source DC identifies the 
enhanced metafile DC. 


Seealso TPoint class, TRect class 


Chord | 

~ bool Chord(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4); 
bool Chord(const TRect& r, const TPoint& start, const TPoint& end); | 
Draws and fills a chord (a region bounded by the intersection of an ellipse and a line 
segment) on this DC using the currently selected pen and brush objects. The ellipse is 
specified by a bounding rectangle given either by (x1, y1)/(x2, y2) or by the rectangle R. 
The starting /ending points of the chord are specified either by (x3, y3)/(x4, y4) or by the 
points Start and End. Chord returns true if the call is successful; otherwise, it returns _ 
false. The current position is neither used nor altered by this call. 


Seealso TDC::Arc, TPoint class, TRect class 


- CloseFigure 
bool CloseFigure(); 
32-bit only. Closes an open figure i in this DC's open path bracket by drawing a line from 
the current position to the first point of the figure (usually the point specified by the 
most recent TDC::MoveTo call), and connecting the lines using the current join style for 
this DC. If you close a figure with TDC::LineTo instead of with CloseFigure, end caps 
(instead of a join) are used to create the corner. The call fails if there is no open path 
bracket on this DC. Any line or curve added to the path after a CloseFigure call starts a 
new figure. A figure in a path remains open until it is explicitly closed with CloseFigure 
even if its current position and start point happen to coincide. 


CloseFigure returns true if the call is successful; otherwise, it returns false. 
Seealso TDC::BeginPath, TDC::EndPath 


DPtoLP 

bool DPtoLP(TPoint* points, int count = 1) const; 

Converts each of the count points in the points array from device points to logical points. 
The conversion depends on this DC's current mapping mode and the settings of its © 
window and viewport origins and extents. DPtoLP returns true if the call is successful; 
otherwise, it returns false. 


Seealso TDC::LPtoDP, TPoint class 


DrawFocusRect 

bool DrawFocusRect(int x1, int x2, int y1, int y2); 

bool DrawFocusRect(const TRect& rect); 

Draws the given rectangle on this DC in the style used to indicate focus. Calling the 
function a second time with the same rect argument will remove the rectangle from the 
display. A rectangle drawn with DrawFocusRect cannot be scolled. DrawFocusRect 
returns true if the call is successful; otherwise, it returns false. 
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Seealso TRect class 


Drawicon 

bool Drawlcon(int x, int y, const Tlcon& icon); 

bool Drawicon(const TPoint& point, const Ticon& icon); 

Draws the given icon on this DC. The upper left corner of the drawn icon can be 
specified by x- and y-coordinates or by the point argument. Drawlcon returns true if the 
call is successful; otherwise, it returns false. 


Seealso Tlcon class 


DrawText 

virtual boo! DrawText(const char far* string, int count, const TRect& r, uinti6 format = 0); 

Formats and draws in the given rectangle, r, up to count characters of the null- 
terminated string using the current font for this DC. If count is -1, the whole string is 
written. The rectangle must be specified in logical units. Formatting is controlled with 
the format argument, which can be various combinations of the following values: 


ee 


DT BOTTOM 


CMG 

| Specifies bottom-justified text. This value must be combined (bitwise OR'd) 

with DT_SINGLELINE. | 

DT_CALCRECT Determines the width and height of the rectangle. If there are multiple lines 
of text, DrawText uses the width of r (the rectangle argument) and extends 
the base of the rectangle to bound the last line of text. If there is only one line 
of text, DrawText uses a modified value for the right side of r so that it 
bounds the last character in the line. In both cases, DrawText returns the 
height of the formatted text but does not draw the text. 


DT_CENTER Centers text horizontally. 
DT_EXPANDTABS Expands tab characters. The default number of characters per tab is eight. 


DT_EXTERNALLEADING _ Includes the font external leading in line height. Normally, external leading 
| is not included in the height of a line of text. 


DT_LEFT Aligns text flush-left. 

DT_NOCLIP Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is 
| used. | 

DT_NOPREFIX Turns off processing of prefix characters. Normally, DrawText interprets the 


prefix character & as a directive to underscore the character that follows, and 
the prefix characters && as a directive to print a single &. By specifying 
DT_NOPREFIX, this processing is turned off. 


DT_RIGHT Aligns text flush-right. 

DT_SINGLELINE Specifies single line only. Carriage returns and linefeeds do not break the 
line. 

DT_TABSTOP Sets tab stops. Bits 15-8 (the high-order byte of the low-order word) of the 


format argument are the number of characters for each tab. The default 
number of characters per tab is eight. 


DT_TOP Specifies top-justified text (single line only). 
DT_VCENTER Specifies vertically centered text (single line only). 
DT_WORDBREAK Specifies word breaking. Lines are automatically broken between words if a 


word would extend past the edge of the rectangle specified by r. A carriage 
return/line sequence will also break the line. 


Note that the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, 
DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value. 
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DrawText uses this DC's currently selected font, text color, and background color to 
draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so that it 
does not appear outside the given rectangle. All formatting is assumed to have multiple 
lines unless the DT_SINGLELINE format is given. 7 


If the selected font is too large for the specified rectangle, DrawText aves not attempt to 
substitute a smaller font. 


If successful, DrawText returns true; otherwise, returns false. 
See also TDC::GrayString, TDC::TabbedTextOut, TDC::TextOut, TRect class 


Ellipse 

bool Ellipse(int x1, int y1, int x2, int y2); 

bool Ellipse(const TPoint& p1, const TPoint& p2); 

bool Ellipse(const TPoint& point, const TSize& size); 

bool Ellipse(const TRect& rect); | 

Draws and fills an ellipse on this DC using the currently selected pen and brush objects. 
The center of the ellipse is the center of the bounding rectangle specified either by (x1, 

y1)/(x2, y2) or by the rect argument. Ellipse returns true if the call is successful; 

otherwise, it returns false. The current position is neither used nor altered by this call. 


See also TDC::Arc, TPoint class, TRect class, TSize class 


EndPath | 

bool EndPath(); 

32-bit only. Closes the path bracket and selects the path it defines into this DC. Returns 
true if the call is successful; otherwise, returns false. : 


Seealso TDC::BeginPath, TDC::CloseFigure 


EnumFontFamilies 

int EnumFontFamilies(const char far* family, FONTENUMPROC proc, void far* data) const; 

Enumerates the fonts available to this DC in the font family specified by family. The 
given application-defined callback proc is called for each font i in the family or until proc 
returns 0, and is defined as 


typedef int (CALLBACK* FONTENUMPROC) (CONST LOGFONT *, CONST TEXTMETRIC *, DWORD, LPARAM); 


data lets you pass both application-specific data and font data to proc. If successful, the 
call returns the last value returned by proc. 


See also TDC::EnumFonts, LOGFONT struct, TEXTMETRIC struct 


EnumFonts 

int EnumFonts(const char far* faceName, OLDFONTENUMPROC callback, void far* data) const; 
Enumerates the fonts available on this DC for the given faceName. The font type, 
LOGFONT, and TEXTMETRIC data retrieved for each available font is passed to the 
user-defined callback function together with any optional, user-supplied data placed in 
the data buffer. The callback function can process this data in any way desired. 
Enumeration continues until there are no more fonts or until the callback function 
returns 0. If faceName is 0, EnumFonts randomly selects and enumerates one font of each 
available typeface. EnumFonts returns the last value returned by the callback function. 
Note that OLDFONTENUMPROC is defined as FONTENUMPROC for Win32 only. 
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FONTENUMPROC is a pointer to a user-defined function and has the following 
prototype: 
int CALLBACK EnumFontsProc(LOGFONT *lplf, TEXTMETRIC *lptm, uint32 dwIype, LPARAM lpData) ; 


where dwType specifies one of the following font types: DEVICE_FONTTYPE, 
RASTER_FONTTYPE, or TRUETYPE_FONTTYPE. 


See also TDC::EnumFontFamilies, LOGFONT struct, TEXTMETRIC struct 


EnumMetaFile 

int EnumMetaFile(const TMetaFilePict& metaFile, MFENUMPROC callback, void* data) const; 

Enumerates the GDI calls within the given metaFile. Each such call is retrieved and 
passed to the given callback function, together with any client data from data, until all 
calls have been processed or a callback function returns 0. MFENUMPROC is defined as 


typedef int (CALLBACK* MFENUMPROC) (HDC, HANDLETABLE FAR*, METARECORD FAR*, int, LPARAM) ; 
Seealso TDC::PlayMetaFile, METARECORD struct 


EnumObjects | 

int EnumObjects(uint objectType, GOBUENUMPROC proc, void far* data) const; 

Enumerates the pen or brush objects available for this DC. The parameter objectT ype can 
be either OBJ_BRUSH or OBJ_PEN. For each pen or brush found, proc, a user-defined 
callback function, is called until there are no more objects found or the callback function 
returns 0). proc is defined as 


typedef int (CALLBACK* GOBJENUMPROC) (LPVOID, LPARAM) ; 


Parameter data specifies an application-defined value that is passed to proc. 


ExcludeClipRect 

int ExcludeClipRect(const TRect& rect); 

Creates a new clipping region for this DC. This new region consists of the current 
clipping region minus the given rectangle, rect. The return value indicates the new 
clipping region's type as follows: 


‘Region oo 
COMPLEXREGION Clipping Region has overlapping borders. 
ERROR Invalid DC. 

NULLREGION Clipping region is empty. 

SIMPLEREGION Clipping region has no overlapping borders. 


See also TDC::GetClipBox, TRect class 


ExcludeUpdateRgn 
int ExcludeUpdateRgn(HWND wnd); 
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Prevents drawing within invalid areas si a window by excluding an updated region of 
this DC's window from its clipping region. The return value indicates the resulting 
clipping region's type as follows: : 


COMPLEXREGION Clipping Region has overlapping borders 


ERROR Invalid DC. 

NULLREGION Clipping region is empty. 

SIMPLEREGION —_. Clipping region has no overlapping borders. 
ExtFloodFil 


bool ExtFloodFill(const TPoint& Bain TColor color, uinti6 fill Type): 

Fills an area on this DC starting at point and using the currently selected brush object. 
The color argument specifies the color of the boundary or of the region to be filled. The 
fillType argument specifies the type of fill, as follows: 


FLOODFILLBORDER The fill region is bounded by the given color. This style coincides with the filling 
method used by FloodFill. 


FLOODFILLSURFACE The fill region is defined by the given color. Filling continues outward in all 
directions as long as this color is encountered. Use this style when filling 
regions with multicolored borders. 


Not every device supports ExtFloodFill, so applications should test first with 
TDC::GetDeviceCaps. 


ExtFloodFill returns true if the call is successful; otherwise, it returns false. 
See also TDC::FloodFill, TDC::GetDeviceCaps, TColor class, TPoint class 


ExtTextOut | 

virtual bool ExtTextOut(int x, int y, uint16 options, const TReet* const char far* string, int count, const 
int far* dx = 0); 

bool ExtTextOut(const TPoint& p, uint16 options: const TRect* r, const char far* string, int count, const 
int far* dx = 0); 


Draws up to count characters of the given diliierminsied string in the current font on 
this DC. If count is -1, the whole string is written. 


An optional rectangle r can be specified for clipping, opaquing, or both, as detecwined 
by the options value. If options is set to ETO_CLIPPED, the rectangle is used for clipping 
the drawn text. If options is set to ETO_LOPAQUE, the current background color is used 
to fill the rectangle. Both options can be used if ETO_CLIPPED is OR'd with 
ETO_OPAQUE. 


The (x, y) 0 rp arguments specify the logical coordinates of the reference point that is 
used to align the first character. The current text-alignment mode can be inspected with 
TDC::GetTextAlign and changed with TDC::SetTextAlign. By default, the current position 
is neither used nor altered by ExtTextOut. However, if the align mode is set to 
TA_UPDATECP, ExtTextOut ignores the reference point argument(s) and uses or 
updates the current position as the reference point. 


128 ObjectWindows Reference Guide 


TDC class 


The dx argument is an optional array of values used to set the distances between the 
origins (upper left corners) of adjacent character cells. For example, dx/i] represents the 
number of logical units separating the origins of character cells 7 and i+1. If dx is 0, 
ExtTextOut uses the default inter-character spacings. 


ExtTextOut returns true if the call is successful; otherwise, it returns false. 
Seealso TDC::TextOut, TDC::GetTextAlign, TDC::TabbedTextOut, TPoint, TRect 


FillPath 

bool FillPath(); 

32-bit only. Closes any open figures in the current patn of this DC and fills the path's 
interior using the current brush and polygon fill mode. After filling the interior, FillPath 
discards the path from this DC. 


FillPath returns true if the call is successful; otherwise, it returns false. 


Seealso TDC::BeginPath, TDC::CloseFigure, TDC::StrokePath, 
TDC::StrokeAndFillPath, TDC::SetPolyFillMode 


FillRect 

bool FillRect(int x1, int y1, int x2, int y2, const TBrush& brush); 

bool FillRect(const TRect& rect, const TBrush& brush); 

Fills the given rectangle on this DC using the specified brush. The fill covers the left and 
top borders but excludes the right and bottom borders. FillRect returns true if the call is 
successful; otherwise, it returns false. 


Seealso TBrush, TRect 


FillRgn 

bool FillRgn(const TRegion& region, const TBrush& brush); 

Fills the given region on this DC using the specified brush. FillRgn returns true if the call 
is successful; otherwise, it returns false. 


Seealso TDC::InvertRkgn, TDC::PaintRgn, TBrush class, TRegion class 


FlattenPath 

bool FlattenPath(); 

32-bit only. Transforms any curves in the currently selected path of this DC. All such 
curves are changed to sequences of linear segments. Returns true if the call is successful; 
otherwise, returns false. 


See also TDC::WidenPath, TDC::BeginPath — 


FloodFill 

bool FloodFill(const TPoint& point, TColor color); 

Fills an area on this DC starting at point and using the currently selected brush object. 
The color argument specifies the color of the boundary or of the area to be filled. Returns 
true if the call is successful; otherwise, returns false. FloodFill is maintained in the WIN32 
API for compatibility with earlier APIs. New WIN32 applications should use 
TDC::ExtFloodFill. 


Seealso TDC::ExtFloodFill, TColor, TPoint 
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FrameRect 

bool FrameRect(int x1, int x2, int y1, int y2, const TBrush& brush); 

bool FrameRect(const TRect& rect, const TBrush& brush); 

Draws a border on this DC around the given rectangle, rect, using the given brush, 
brush. The height and width of the border is one logical unit. Returns true if the call is 
successful; otherwise, it returns false. 


See also TBrush class, TRect class 


FrameRgn 

bool FrameRgn(const TRegion& region, const TBrush& brush, const TPoint& p); | | 
Draws a border ori this DC around the given region, region, using the given brush, brush. 
The width and height of the border is specified by the p argument. Returns true if the 
call is successful; otherwise, returns false. 


Seealso Brush class, TRegion class 


GetAspectRatioFilter 
bool GetAspectRatioFilter(TSize& size) const; 
Retrieves the setting of the current aspect-ratio filter for this DC. 


Seealso TSize 


GetBkColor 
TColor GetBkColor() const; | 
Returns the current background color of this DC. 


See also TDC::SetBkColor, TColor class 


GetBkMode 
int GetBkMode() const; 
Returns the background mode of this DC, either OPAQUE or TRANSPARENT. 


See also TDC: ‘SetBkMode 


GetBoundsRect 

bool GetBoundsRect(TRect& bounds, uint16 flags) const; 

Reports in bounds the current accumulated bounding rectangle of this DC or of the 
Windows manager, depending on the value of flags. Returns true if the call is successful; 
otherwise, returns false. 


The flags argument can be DCB_RESET or DCB_WINDOWMGR or both. The flags value 
work as follows: 


DCB_RESET Forces the bounding rectangle to be cleared after being set in bounds. 
DCB_WINDOWMGER __ Reports the Windows current bounding rectangle rather than that of this DC. 


There are two bounding-rectangle accumulations, one for Windows and one for the 
application. GetBoundsRect returns screen coordinates for the Windows bounds, and 
logical units for the application bounds. The Windows accumulated bounds can be 
queried by an application but not altered. The application can both query and alter the 
DC's accumulated bounds. 
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See also TDC::SetBoundsRect, TRect class 


GetBrushOrg 

bool GetBrushOrg(TPoint& point) const; 

Places in point the current brush origin of this DC. Returns true if successful; otherwise, 
returns false. 7 


Seealso TPoint class 


GetCharABCWidths 

boo! GetCharABCWidths(uint firstChar, uint lastChar, ABC* abc); 

Retrieves the widths of consecutive characters in the range firstChar to lastChar from the 
current TrueType font of this DC. The widths are reported in the array abc of ABC 
structures. Returns true if the call is successful; otherwise, returns false. 


Seealso TDC::GetCharWidth, ABC struct 


GetCharWidth 

bool GetCharWidth(uint firstChar, uint lastChar, int* buffer); 

Retrieves the widths in logical units for a consecutive sequence of characters in the 
current font for this DC. The sequence is specified by the inclusive range, firstChar to 
lastChar, and the widths are copied to the given buffer. If a character in the range is not 
represented in the current font, the width of the default character is assigned. Returns 
true if the call is successful; otherwise, returns false. 


See also TDC::GetCharABCWidths 


GetClipBox 

int GetClipBox(TRect& rect) const; 

TRect GetClipBox() const; 

Places the current clip box size of this DC in rect. The clip box is defined as the emaliest 
rectangle bounding the current clipping boundary. The return value indicates the 
clipping region's type as follows: 


COMPLEXREGION Clipping Region has overlapping borders 


ERROR Invalid DC. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 


Seealso TDC::ExcludeClipRect, TRect class 


GetClipRgn 

bool GetClipRgn(TRegion& region) const; 

Retrieves this DC's current clip-region and, if successful, places a copy of it in the region 
argument. You can alter this copy without affecting the current clip-region. Returns true 
if the call is successful; otherwise, returns false. 


Seealso [Region 


GetCurrentObject 
HANDLE GetCurrentObject(uint objectType) const; 
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Returns a handle to the currently selected object of the given objectType associated with _ 
this DC. Returns 0 if the call fails. objectT'ype can be OBJ_PEN, OBJ_BRUSH, OPI_ PAL, | 
OBJ_FONT, or OBJ_BITMAP. 


GetCurrentPosition 

bool GetCurrentPosition(TPoint& point) const; 

Reports in point the logical coordinates of this DC's current position. Returns true if the 
call is successful; otherwise, returns false. 


Seealso TPoint class 


GetDCOrg | 

bool GetDCOrg(TPoint& point) const; 

Obtains the final translation origin for this device context and places the value in point. 
This value specifies the offset used to translate device coordinates to client coordinates 
for points in an application window. Returns true if the call is successful; otherwise, 
returns false. 


Seealso TPoint class 


GetDeviceCaps 

virtual int GetDeviceCaps(int index) const; : 
Used under WIN3.1 or later, GetDeviceCaps returns capability information about this 
DC. The index argument specifies the type of information required. 


GetDIBits 
boo! GetDIBits(const TBitmap& pitta uint16 startScan, uint16 numScans, void HUGE* bits, 

const BITMAPINFO far& info, uinti6 usage); 
bool GetDIBits(const TBitmap& bitmap, TDib& dib); 
The first version retrieves some or all of the bits from the given bitmap on this DC and 
copies them to the bits buffer using the DIB (device-independent bitmap) format 
specified by the BITMAPINFO argument, info. numScan scanlines of the bitmap are 
retrieved, starting at scan line startScan. The usage argument determines the format of 
the bmiColors member of the BITMAPINFO structure, according to the following table: 


€ color table 1S an array O “bit idaexes into the current logical palette. 


DIB_RGB_ COLORS The color table contains literal RGB values. 


DIB_PAL_ INDICES There is no color table for this bitmap. The DIB bits consist of indexes into the 
| system palette. No color translation occurs. Only the BITIMAPINFOHEADER 
portion of BITMAPINFO is filled in. 


In the second version of GetDIBits, the bits are retrieved from bitmap and placed in the 
dib.Bits data member of the given TDib areuene The BITMAPINFO argument is 
supplied from dib.info. 


GetDIBits returns true if the call is successful; otherwise, it returns false. 


Seealso TDC::SetDIBits, TBitmap, TDib, BITMAPINFO struct 


GetFontData 
uint32 GetFontData(uint32 table, uint32 offset, void* buffer, long data); 
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Retrieves font-metric information from a scalable TrueType font file (specified by table 
and starting at offset into this table) and places it in the given buffer. data specifies the size 
in bytes of the data to be retrieved. If the call is successful, it returns the number of bytes 
set in buffer; otherwise, —1 is returned. 


GetGlyphOutline 
uint32 GetGlyphOutline (uint chr, uint format, GLYPHMETRICS far& gm, uint32 buffSize, voidfar* buffer, 

const MAT2 far& mat2); 
Retrieves TrueType metric and other data for the given character, chr, on this DC and 
places it in gm and buffer. The format argument specifies the format of the retrieved data 
as indicated in the following table. (A value of 0 simply fills in the GLYPHMETRICS 
structure but does not return glyph-outline data.) 


Value Meaning 
1 Retrieves the glyph bitmap. 


Z Retrieves the curve data points in the rasterizer's native format and uses the font's design units. 
With this value of format, the mat2 transformation argument is ignored. 


The gm argument specifies the GLYPHMETRICS structure that describes the placement 
of the glyph in the character cell. buffSize specifies the size of buffer that receives data 
about the outline character. If either buffSize or buffer is 0, GetGlyphOutline returns the 
required buffer size. Applications can rotate characters retrieved in bitmap format 
(format = 1) by specifying a 2 x 2 transformation matrix via the mat2 argument. 


GetGlyphOutline returns a positive number if the call is successful; otherwise, it returns 
GDI_ERROR. 


Seealso TDC::GetOutlineTextMetrics, GLYPHMETRICS struct 


GetKerningPairs 

int GetKerningPairs(int pairs, KERNINGPAIR far* krnPair); 

Retrieves kerning pairs for the current font of this DC up to the number specified in pairs 
and copies them into the krnPair array of KERNINGPAIR structures. If successful, the 
function returns the actual number of pairs retrieved. If the font has more than pairs 
kerning pairs, the call fails and returns 0. The krnPair array must allow for at least pairs 
KERNINGPAIR structures. If krnPair is set to 0, GetKerningPairs returns the total 
number of kerning pairs for the current font. 


See also KERNINGPAIR struct 
GetMapMode 
int GetMapMode() const; 


If successful, returns the current window mapping mode of this DC; otherwise, returns 
0. The mapping mode defines how logical coordinates are mapped to device 
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coordinates. It also controls the orientation of the device's x- ‘and y-axes. The mode 
values are shown i in the following table: 


& app ry Maas 
SetWindowExtEx and SetViewportExtEx must be used to specify the desired 
units, orientation, and scaling. 


MM_HIENGLISH Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is at 
the top. 

MM_HIMETRIC Each logical unit is mapped to 0.01 altinaaiee Positive x is to the eae positive y 
is at the top. 

MM_ISOTROPIC Logical units are mapped to arbitrary units with equally scaled axes; that is, one 


unit along the x-axis is equal to one unit along the y-axis. SetWindowExtEx and 
Set ViewportExtEx must be used to specify the desired units and the orientation of 
the axes. GDI makes adjustments as necessary to ensure that the x and y units 
remain the same size (e.g., if you set the window extent, the viewport is adjusted 
to keep the units isotropic). 


MM_LOENGLISH Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is at 
| the top. - 
MM_LOMETRIC Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y 
| is at the top. 
MM_TEXT Each logical unit is mapped to one device pixel. Positive x is to the right; positive 
y is at the bottom. 
MM_TWIPS Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch). 


Positive x is to the right; positive y is at the top. 


See also TDC::SetMapMode 


GetNearestColor 
TColor GetNearestColor(TColor Color) const; 
Returns the color nearest to the given Color argument for the current palette of this DC. 


Seealso TColor 


GetOutlineTextMetrics 

uint32 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm); 

uint!6 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm); 

Retrieves metric information for TrueType fonts on this DC and copies it to the given 
array of OUTLINETEXTMETRIC structures, otm. This structure contains a 
TEXTMETRIC and several other metric members, as well as four string-pointer 
members for holding family, face, style, and full font names. Since memory must be 
allocated for these variable-length strings in addition to the font metric data, you must 
pass (with the data argument) the total number of bytes required for the retrieved data. 
If GetOutlineTextMetrics is called with otm = 0, the function returns the total buffer size 
required. You can then assign this value to data in subsequent calls. 


Returns nonzero if the call is successful; otherwise, returns 0. 


Seealso TDC::GetTextMetrics, OUTLINETEXTMETRIC struct, TEXTMETRIC struct 


GetPixel — 
TColor GetPixel(int x, int y) const; 
TColor GetPixel(const TPoint& point) const; 
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Returns the color of the pixel at the given location. 
Seealso TDC::SetPixel, TPoint class 


GetPolyFillMode 

int GetPolyFillMode() const; 

Returns the current polygon-filling mode for this DC, either ALTERNATE or 
WINDING. 


See also TDC::SetPolyFillMode 


GetROP2() 
int GetROP2() const; 
Returns the current drawing (raster operation) mode of this DC. 


Seealso TDC::SetROP2 


GetStretchBitMode 

int GetStretchBltMode() const; 

Returns the current stretching mode for this DC: BLAACKONWHITE, 
COLORONCOLOR, or WHITEONBLACK. The stretching mode determines how 
bitmaps are stretched or compressed by the StretchBlt function. 


Seealso TDC::SetStretchBltMode, TDC::StretchBlt 


GetSystemPaletteEntries 

uint GetSystemPaletteEntries(int start, int num, PALETTEENTRY far* entries) const; 

Retrieves a range of up to num palette entries, starting at start, from the system palette to 
the entries array of PALETTEENTRY structures. Returns the actual number of entries 
transferred. 


See also PALETTEENTRY struct 


GetSystemPaletteUse 
uint GetSystemPaletteUse() const; 


Determines whether this DC has access to the full system palette. Returns 
SYSPAL_NOSTATIC or SYSPAL_STATIC. 


Seealso TDC::SetSystemPaletteUse 


GetTabbedTextExtent 
bool GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions, 

TSize& size) const; 
TSize GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions) const 
Computes the extent (width and height) in logical units of the text line consisting of 
stringLen characters from the null-terminated string. The extent is calculated from the 
metrics of the current font or this DC, but ignores the current clipping region. In the first 
version of GetTabbedTextExtent, the extent is returned in size; in the second version, the 
extent is the returned T’Size object. Width is size.x and width is size.y. 


The width calculation includes the spaces implied by any tab codes in the string. Such 
tab codes are interpreted using the numPositions and positions arguments. The positions 
array specifies numPositions tab stops given in device units. The tab stops must have 
strictly increasing values in the array. If numPositions and positions are both 0, tabs are 
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expanded to eight times the average character width. If numPositions is 1, all tab stops: 
are taken to be positions[0] apart. | 7 


If kerning is being applied, the sum of the extents of the characters in a string might not 
equal the extent of the string. 


See also TDC::TabbedTextOut, TDC::GetTextExtent, TSize class 


GetTextAlign 

uint GetTextAlign() const; 

If successful, returns the current text-alignment flags for this DC; otherwise, returns the 
value GDI_ERROR. The text-alignment flags determine how TDC::TextOut and 
TDC::ExtTextOut align text strings in relation to the first character's screen position. 
GetTextAlign returns certain combinations of the flags listed in the following table: 


e€ rererence pom Ww. e on the paseime oO e text. 


TA_BOTTOM The reference point will be on the bottom edge of the bounding rectangle. 
TA_TOP » The reference point will be on the top edge of the bounding rectangle. 

| The reference point will be aligned horizontally with the center of the boundin 
TA_CENTER P on »: 8S 
oN a rectangle. 


The reference point will be on the left edge of the bounding rectangle. 
TA_RIGHT The reference point will be on the right edge of the bounding rectangle. 
TA_NOUPDATECP _ The current position is not updated after each text output call. 
TA.UPDATECP The current position is updated after each text output call. 


When the current font has a vertical default baseline (as with Kanji) the following 
values replace TA_BASELINE and TA_CENTER: 


VTA_BASELINE The reference point will be on the baseline of the text. 


VTA_CENTER The reference point will be aligned vertically with the 
center of the bounding rectangle. 


The text-alignment flags are not necessarily single bit-flags and might be equal to 0. The 
flags must be examined in groups of the following related flags: 

¢ TA_LEFT, TA_RIGHT, and TA_CENTER 

e TA_BOTTOM, TA_TOP, and TA_BASELINE 

e TA_NOUPDATECP and TA _UPDATECP 


If the current font has a vertical default baseline (as with Kanji), these are > groups of 
related flags: 


¢ TA_LEFT, TA_RIGHT, and VIA_BASELINE 
¢ TA BOTTOM, TA_TOP, and VTA_CENTER > 
¢ TA_NOUPDATECP and TA_UPDATECP 


To verify that a particular flag is set in the return value of this function, the application 
must perform the following steps: 


1 Apply the bitwise OR operator to the flag and its related hia 
2 Apply the bitwise AND operator to the result and the return value. — 
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3 Test for the equality of this result and the flag. 


The following example shows a method for determining which horizontal alignment 
flag is set: 


switch ((TA_LEFT | TA_RIGHT | TA_CENTER) & dc.GetTextAlign()) { 
case TA LEFT: 


case TA RIGHT: 
case TA CENTER: 


} 
Seealso TDC::SetTextAlign, TDC::TextOut, TDC::ExtTextOut 


GetTextCharacterExtra 
int GetTextCharacterExtra() const; 


If successful, returns the current intercharacter spacing, in logical units, for this DC; 
otherwise, returns INVALID_WIDTH. 


Seealso TDC::SetTextCharacterExtra 


GetTextColor 
TColor GetTextColor() const; 


Returns the current text color of this DC. The text color determines the color displayed 
by TDC::TextOut and TDC::ExtTextOut. 


Seealso TDC::SetTextColor, TDC::TextOut, TDC::ExtTextOut, TColor 


GetTextExtent 

bool GetTextExtent(const char far* string, int stringLen, TSize& size); 

TSize GetTextExtent(const char far* string, int stringLen); 

Computes the extent (width and height) in logical units of the text line consisting of 
stringLen characters from the null-terminated string. The extent is calculated from the 
metrics of the current font or this DC, but ignores the current clipping region. In the first 
version of GetTextExtent the extent is returned in size; in the second version, the extent is 
the returned TSize object. Width is size.x and height is size.y. 


If kerning is being applied, the sum of the extents of the characters in a string might not 
equal the extent of the string. 


Seealso TSize class 

GetTextFace 

int GetTextFace(int count, char far* facename) const; 

Retrieves the typeface name for the current font on this DC. Up to count characters of 


this name are copied to facename. If successful, GetTextFace returns the number of 
characters actually copied; otherwise, it returns 0. 


~Seealso TDC::GetTextAlign, TDC::GetTextMetrics 


GetTextMetrics 
bool GetTextMetrics(TEXTMETRIC far& metrics) const; 
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Fills the metrics structure with metrics data for the current fine on this DC. Returns true 
if the call is successful; otherwise, returns false. , 


See also TEXTMETRIC struct 


GetViewportExt 
bool GetViewportExt(TSize& extent) const; 
TSize GetViewportExt() const; 

The first version retrieves this DC's current viewport's x- and y-extents (in device units) 
and places the values in extent. This version returns true if the call is successful; 
otherwise, it returns false. The second version returns only these x- and y-extents. 


The extent value determines the amount of stretching or compression needed in the 
logical coordinate system to fit the device coordinate system. extent also determines the 
relative orientation of the two coordinate systems. 


Seealso TDC::SetViewportExt, TSize class 


GetViewportOrg 
bool GetViewportOrg(TPoint& point) const, 
TPoint GetViewportOrg() const; 

_ The first version sets in the point argument the x- and y-extents (in device-units) of this 
DC's viewport. It returns true if the call is successful; otherwise, it returns false. The 
second version returns the x- and y-extents (in device-units) of this DC's viewport. 


Seealso TDC::SetViewportOrg, TDC::OffsetViewportOrg, TPoint class 


— GetWindowExt a: 
‘bool GetWindowExt(TSize& extent) const; 
TSize GetWindowExt() const; 
Retrieves this DC's window current x- and y-extents (in device units). The first version 
places the values in extent and returns true if the call is successful; otherwise, it returns 
false. The second version returns the current extent values. The extent value determines 
the amount of stretching or compression needed in the logical coordinate system to fit 

_ the device coordinate system. extent also determines the relative orientation of the two 
coordinate systems. 


Seealso TDC::SetWindowExt, TSize class 


-GetWindowOrg 
bool GetWindowOrg(TPoint& point) const; 
TPoint GetWindowOrg() const; 
Places in point the x- and y-coordinates of the origin of the window associated with this 
DC. Returns true if the call is successful; otherwise, returns false. 


Seealso TDC::SetWindowOrg, TDC::OffsetWindowOrg, TPoint class 


GrayString 

virtual bool GrayString(const TBrush& brush, GRAYSTRINGPROC outputFunc, const char far* string, int count, 
const TRecté r); 

Draws in the given rectangle (r) up to count characters of gray text from string using the 

given brush, brush, and the current font for this DC. If count is -1 and string is null- | 

terminated, the whole string is written. The rectangle must be specified in logical units. 
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If brush is 0, the text is grayed with the same brush used to draw window text on this 
DC. Gray text is primarily used to indicate disabled commands and menu items. 


GrayString writes the selected text toa memory bitmap, grays the bitmap, then displays 
the result. The graying is performed regardless of the current brush and background 
color. 


The outputFunc pointer to a function can specify the procedure instance of an 
application-supplied drawing function and is defined as 


typedef BOOL (CALLBACK* GRAYSTRINGPROC) (HDC, LPARAM, int); 


If outputFunc is 0, GrayString uses TextOut and string is assumed to be a normal, null- 
terminated character string. If string cannot be handled by TextOut (for example, the 
string is stored as a bitmap), you must provide a suitable drawing function via 
outputFunc. 


If the device supports a solid gray color, it is possible to draw gray strings directly 
without using GraySring. Call GetSysColor to find the color value; for example, G of 
COLOR_GRAYTEXT. If G is nonzero (non-black), you can set the text color with 
SetTextColor(G) and then use any convenient text-drawing function. 


GrayString returns true if the call is successful; otherwise, it returns false. Failure can 
result if TextOut or outputFunc return false, or if there is insufficient memory to create 
the bitmap. 


Seealso TDC::TextOut, TBrush class, TRect class 


operator HDC() 
operator HDC() const{return Handle;} 


Typecasting operator. Converts a pointer to type HDC (the data type representing the 
handle to a DC). 


IntersectClipRect 

int IntersectClipRect(const TRect& rect); 

Creates a new clipping region for this DC's window by forming the intersection of the 
current region with the rectangle specified by rect. The return value indicates the 
resulting clipping region's type as follows: 


‘COMPLEXREGION Clipping Region has overlapping borders. 


ERROR Invalid DC. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 


Seealso TDC::GetClipBox, TRect class 


InvertRect 

bool InvertRect(int x1, int x2, int y1, int y2); 

bool InvertRect(const TRect& rect); 

Inverts the given rectangle, rect, on this DC. On Rreneetone displays, black and white - 
pixels are interchanged. On color displays, inversion depends on how the colors are 


Chapter 2, ObjectWindows library reference 139 


TDC class 


generated for particular displays. Calling InvertRect an even number of times restores _ 
the original colors. InvertRect returns true if the call is successful; otherwise, it returns 
false. | 


See also TRect class 


InvertRgn 

bool InvertRgn(const TRegion& region); 

Inverts the given region, on this DC. On monochrome displays, black and white ones 
are interchanged. On color displays, inversion depends on how the colors are generated 
for particular displays. Calling InvertRegion an even number (n>=2 ) of times restores the — 
original colors. Returns true if the call is successful; otherwise, it returns false. 


~Seealso TDC::PaintRgn, TDC::FillRgn, TRegion class 


LineTo 

bool LineTo(int x, int y); 

bool LineTo(const TPoint& point); 

Draws a line on this DC using the current pen object. The line is drawn from the current 
position up to, but not including, the given end point, which is specified by (x, y) or by 
point. If the call is successful, LineTo returns true and the current point is reset to point; 
otherwise, it returns false. 


Seealso JPoint 


LPtoDP 

bool LPtoDP(TPoint* points, int count = 1) const: 

Converts each of the count points in the points array from logical points to device points. 
The conversion depends on this DC's current mapping mode and the settings of its 
window and viewport origins and extents. Returns true if the call is successful; 
otherwise, it returns false. 


Seealso TDC::DPtoLP, TPoint 


MaskBit 
bool MaskBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, const TBitmap& maskBm, 
const TPoint& maskPos, uint32 rop=SRCCOPY); 

_ Copies a bitmap from the given source DC to this DC. MaskBIt combines the color data 
from source and destination bitmaps using the given mask and raster operation. The 
srcDC argument specifies the DC from which the source bitmap will be copied. The 
destination bitmap is given by the rectangle, dst. The source bitmap has the same width 
and height as dst. The src argument specifies the logical coordinates of the upper left 
corner of the source bitmap. The maskBm argument specifies a monochrome mask 
bitmap. An error will occur if maskBm is not monochrome. The maskPos argument gives 
the upper left corner coordinates of the mask. The raster-operation code, rop, specifies 
how the source, mask, and destination bitmaps combine to produce the new destination 

_ bitmap. The raster-operation codes are as follows: 


BLACKNESS Fill dst with index-O color of ee palette (default is black). 
DSTINVERT Invert dst. 
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Value of rop 
MERGECOPY 
MERGEPAINT 
NOTSRCCOPY 
NOTSRCERASE 
PATCOPY 
PATINVERT 
PATPAINT 


SRCAND 
SRCCOPY 
SRCERASE 
SRCPAINT 
WHITENESS 
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Meaning 7 — 

Merge the colors of source with mask with Boolean AND. 

Merge the colors of inverted-source with the colors of dst using Boolean OR. 
Copy inverted-source to dst. 

Combine the colors of source and dst using Boolean OR, then invert result. 
Copy mask to dst. 

Combine the colors of mask with the colors of dst using Boolean XOR. 


Combine the colors of mask with the colors of inverted-source using Boolean 
OR, then combine the result with the colors of dst using Boolean OR. 


Combine the colors of source and dst using the Boolean AND. 

Copy source directly to dst. 

Combine the inverted colors of dst with the colors of source using Boolean AND. 
Combine the colors of source and dst using Boolean OR. 

Fill dst with index-1 color of physical palette (default is white). 


If rop indicates an operation that excludes the source bitmap, the srcDC argument must 
be 0. A value of 1 in the mask indicates that the destination and source pixel colors 
should be combined using the high-order word of rop. A value of 0.in the mask indicates 
that the destination and source pixel colors should be combined using the low-order 
word of rop. If the mask rectangle is smaller than dst, the mask pattern will be suitably 


duplicated. 


When recording an enhanced metafile, an error occurs if the source DC identifies the 
enhanced metafile DC. 


If a rotation or shear transformation is in effect for the source DC when MaskBIit is called, 
an error occurs. Other transformations are allowed. If necessary, MaskBlt will adjust the 
destination and mask color formats to match that of the source bitmaps. Before using 
MaskBIt, an application should call GetDeviceCaps to determine if the source and 
destination DCs support MaskBlt. 


MaskBit returns true if the call is successful; otherwise, it returns false. 
Seealso TDC::BitBlt, TDC::PlgBlt, TDC::GetDeviceCaps, TBitmap class, TPoint class, 


TRect class 


ModifyWorldTransform 


bool ModifyWorldTransform(XFORM far& xform, uint32 mode); 
Changes the current world transformation for this DC using the given xform and mode 
arguments. mode determines how the given XFORM structure is applied, as listed 


below. 


‘Value — 


“MWT._ IDENTITY 


- Meaning — 


Resets the current world fe ansformaton using the identity matrix. If this 
mode is specified, the XFORM structure pointed to by /pXform is ignored. 
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MWT_LEFTMULTIPLY Multiplies the current transformation by the data in the XFORM structure. 
(The data in the XFORM structure becomes the left multiplicand, and the 
data for the current transformation becomes the right multiplicand.) 


MWT_RIGHTMULTIPLY, —- Multiplies the current transformation by the data in the XFORM structure. 
, (The data in the XFORM structure becomes the right multiplicand, and the 
data for the current transformation becomes the left multiplicand.) 
ModifyWorldTransform returns true if the call is successful; otherwise, it 
returns false. 


See also TDC::SetWorldTransform, XFORM struct 


MoveTo | 

bool MoveTo(int x, int y); 

bool MoveTo(const TPoint& point); 

bool MoveTo(const TPoint& point, TPoint& oldPoint); 

Moves the current position of this DC to the given x- and y-coordinates or to the given 
point. The third version sets the previous current position in oldPoint. Returns true if the 
call is successful; otherwise, returns false. 


See also TPoint class 


OffsetClipRgn 

int OffsetClipRgn(const TPoint& delta); 

Moves the clipping region of this DC by the x- and y-offsets specified in delta. The return 
value indicates the resulting clipping region's type as follows: 


COMPLEXREGION Clipping region has overlapping borders. 


ERROR | Invalid DC. 
NULLREGION Clipping region is empty. | 
SIMPLEREGION Clipping region has no overlapping borders. 


Seealso TDC::GetClipBox, TPoint class 


OffsetViewportOrg 

virtual bool OffsetViewportOrg(const TPoint& delta, TPoint* oldOrg = 0); 

Modifies this DC's viewport origin relative to the current values. The delta x- and y- 

components are added to the previous origin and the resulting point becomes the new 
- viewport origin. The previous origin is saved in oldOrg. Returns true if the call is 

successful; otherwise, returns false. 


See also acid nen ds TDC::GetViewportOrg, TPoint class 


OffsetWindowOrg 

bool OffsetWindowOrg(const TPoint& delta, TPoint* oldOrg = 0); 

Modifies this DC's window origin relative to the current values. The delta x- and y- 
components are added to the previous origin and the resulting point becomes the new 
window origin. The previous origin is saved in oldOrg. Returns true if the call is 
successful; otherwise, returns false. 
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Seealso TDC::;GetWindowOrg, TDC::SetWindowOrg, TPoint class 


OWLFastWindowFrame 

void OWLFastWindowFrame(TBrush& brush, TRect& rect, int xWidth, int yWidth) 

Draws a frame of the specified size and thickness with the given brush. The old brush is 
restored after completion. 


Seealso TBrush, TRect 


PaintRgn 

bool PaintRgn(const TRegion& region); 

Paints (fills) the given region on this DC using the currently selected brush. Returns true 
if the call is successful; otherwise, returns, false. 


Seealso TDC::FillRgn, TDC::SelectObject, TRegion class 


PatBit 

bool PatBit(int x, int y, int w, int h, uint82 rop=PATCOPY); 

bool PatBit(const TRect& dst, uint32 rop=PATCOPY); 

Paints the given rectangle using the currently selected brush for this DC. The rectangle 
can be specified by its upper left coordinates (x, y), width w, and height h, or by a single 
TRect argument. The raster-operation code, rop, determines how the brush and surface 
color(s) are combined, as explained in the following table: 


‘PATCOPY Copies pattern to destination bitmap. 

PATINVERT. Combines destination bitmap with pattern using the Boolean OR operator. 
DSTINVERT Inverts the destination bitmap. 

BLACKNESS Turns all output to binary 0s. 

WHITENESS Turns all output to binary 1s. 


The allowed values of rop for this function are a limited subset of the full 256 ternary 
raster-operation codes; in particular, an operation code that refers to a source cannot be 
used with PatBit. 


Not all devices support the PatBlt function, so applications should call 
TDC::GetDeviceCaps to check the features supported by this DC. 


PatBlt returns true if the call is successful; otherwise, returns false. 
See also TDC::GetDeviceCaps, TRect class 


PathToRegion 
HRGN PathToRegion(); 
If successful, returns a region created from the closed path in this DC; otherwise, returns 
0. | 


Pie 
bool Pie(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4); 
bool Pie(const TRect& rect, const TPoint& start, const TPoint& end); 


Using the currently selected pen and brush objects, draws and fills a pie-shaped wedge 
by drawing an elliptical arc whose center and end points are joined by lines. The center 
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of the ellipse is the center of the rectangle specified either by (x1, y1)/(x2, y2) or by the 
rect argument. The starting /ending points of pie are specified either by (x3, y3)/(x4, y4) 
-. or by the points Start and End. Returns true if the call is successful; otherwise, returns 
false. The current position is neither used nor altered by this call. : 


Seealso TDC::Chord, TDC: Arc, TPoint class, TRegion class, TRect class 


PlayMetaFile 

bool PlayMetaFile(const TMetaFilePict& metaFile); 

Plays the contents of the given metaFile on this DC. The metafile can be Bagel any 
number of times. Returns true if the call is successful; otherwise, returns false. 


See also class TDC::EnumMetaFile, TDC::PlayMetaFileRecord, TMetaFilePict 


PlayMetaFileRecord 

void PlayMetaFileRecord(HANDLETABLE far& Handletable, METARECORD far& metaRecord, int count); 
Plays the metafile record given in metaRecord to this DC by executing the GDI function 
call contained in that record. Handletable specifies the object handle table to be used. 
count specifies the number of handles in the table. 


Seealso TDC::PlayMetaFile, TDC: ‘EnumMetaFile, HANDLETABLE struct, 
METARECORD struct 


PigBit 
bool PlgBit(const TPoint& dst, const TDC& stcDC, const TRect& src, const TBitmap& maskBm, const TPoint& m 
askPos, uint32 rop=SRCCOPY); 
32-bit only. Performs a bit-block transfer from the given source DC to this DC. Color bits 
are copied from the src rectangle on srcDC, the source DC, to the parallelogram dst on 
this DC. The dst array specifies three points A,B, and C as the corners of the destination 
parallelogram. The fourth point D is generated internally from the vector equation D = B 
+ C-—A. The upper left corner of src is mapped to A, the upper right corner to B, the 
lower left corner to C, and the lower right corner to D. An optional monochrome bitmap 
can be specified by the maskBm argument. (If maskBm specifies a valid monochrome 

_ bitmap, PigBlt uses it to mask the colorbits in the source rectangle. An error occurs if 
maskBm is not a monochrome bitmap.) maskPos specifies the upper left corner 
coordinates of the mask bitmap. With a valid maskBm, a value of 1 in the mask causes 
the source color pixel to be copied to dst; a value of 0 in the mask indicates that the 
corresponding color pixel in dst will not be changed. If the mask rectangle is smaller 
than dst, the mask pattern will be suitably duplicated. 


The destination coordinates are transformed according to this DC (the destination DC). 

The source coordinates are transformed according to the source DC. If a rotation or 

shear transformation is in effect for the source DC when PigBit is called, an error occurs. 

Other transformations, such as scaling, translation, and reflection are allowed. The 

stretching mode of this DC (the destination DC) determines how PigBit will stretch or 

compress the pixels if necessary. When recording an enhanced metafile, an error occurs 
if the source DC identifies the enhanced metafile DC. 


If necessary, PlgBit adjusts the source color formats to match that of the destination. An 
error occurs if the source and destination DCs are incompatible. Before using PlgBlt,an _ 
application should call Coes to determine if the source and destination DCs are 

compatible. 


144 ObjectWindows Reference Guide 


TDC class 


PigBit returns true if the call is successful; otherwise, it returns false. 


Seealso TDC::GetDeviceCaps, TDC::MaskBlt, TDC::SetStretchBltMode,. 
TDC::StretchBlt, TBitmap class, TPoint class, TRect class 


PolyBezier 

bool PolyBezier(const TPoint* points, int count); 

Draws one or more connected cubic Bezier splines through the points specified in the 
points array using the currently selected pen object. The first spline is drawn from the 
first to the fourth point of the array using the second and third points as controls. 
Subsequent splines, if any, each require three additional points in the array, since the 
previous end point is taken as the next spline's start point. The count argument ( >= 4 ) 
specifies the total number of points needed to specify the complete drawing. To draw n 
splines, count must be set to (3n + 1). Returns true if the call is successful; otherwise, 
returns false. The current position is neither used nor altered by this call. The resulting 
figure is not filled. 


Seealso JTDC::PolyBezierTo, TPoint 


PolyBezierTo 

bool PolyBezierTo(const TPoint* points, int count); 

Draws one or more connected cubic Beziers plines through the points specified in the 
points array using the currently selected pen object. The first spline is drawn from the 
current position to the third point of the array using the first and second points as 
controls. Subsequent splines, if any, each require three additional points in the array, 
since the previous end point is taken as the next spline's start point. The count argument 
(>= 4) specifies the total number of points needed to specify the complete drawing. To 
draw n splines, count must be set to 3n. Returns true if the call is successful; otherwise, 
returns false. The current position is moved to the end point of the final Bezier curve. 
The resulting figure is not filled. 


Seealso TDC::PolyBezier, TPoint class 


PolyDraw 

bool PolyDraw(const TPoint* points, uint8* types, int count); 

Using the currently selected pen object, draws one or more possibly disjoint sets of line 
segments or Bezier splines or both on this DC. The count points in the points array 
provide the end points for each line segment or the end points and control points for 
each Bezier spline or both. The count BYTEs in the types array determine as follows how 
the corresponding point in points is to be interpreted: 


5 RETIERTO 


appear in sets of three: the current position is the Bezier start point; the first two 
PT_BEZIERTO points are the Bezier control points; and the third PT_BEZIERTO 
point is the Bezier end point, which becomes the new current point. An error 
occurs if the PT_BEZIERTO types do not appear in sets of three. An end-point 
PT_BEZIERTO can be bit-wise OR'd with PT_CLOSEFIGURE to indicate that 
the current figure is to be closed by drawing a ae from this end point to the 
start point of the most recent disjoint figure. 


PT_CLOSEFIGURE Optional flag that can be bit-wise OR'd with PT_LINETO or PT_BEZIERTO, as 
| explained above. Closure updates the current point to the new end point. — 
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PT_LINETO A line is drawn fromthe current position to this point, which then becomes the 
| new current point. PT_LINETO can be bit-wise OR'd with PT_CLOSEFIGURE _ 
to indicate that the current figure is to be closed by drawing a line segment from 
this point to the start point of the most recent disjoint figure. 


PT_MOVETO > ‘This point starts a new (disjoint) figure and becomes the new current point. 


PolyDraw is an alternative to consecutive calls to MoveTo, LineTo, Polyline, PolyBezier, and 
PolyBezierTo. If there is an active path invoked via BeginPath, PolyDraw will add to this 
path. 


Returns true if the call is Sieeecet otherwise, returns false. 


See also TDC::MoveTo, TDC::LineTo, TDC: :PolyBezier, TDC::PolyBezierTo, 
TDC::Polyline, TDC::BeginPath, TPoint class 


Polygon 

bool Polygon(const TPoint* points, int count); 

Using the current pen and polygon-filling mode, draws and fills on this DC a closed 
polygon with a number of line segments equal to count (which must be >= 2). The points 
array specifies the vertices of the polygon to be drawn. The polygon is automatically 
closed, if necessary, by drawing a line from the last to the first vertex. The current 
position is neither used nor altered by Polygon. Returns true if the call is successful; 
otherwise, returns false. 


Seealso TDC::Polyline, TDC: eeclynuvode TDC: (GetPolyFillMode, TPoint class 


Polyline 
bool Polyline(const TPoint* points, int count) 

Using the current pen object, draws on this DC a count of line segments (there must be at 
least 2). The points array specifies the sequence of points to be connected. The current 
position is neither used nor altered by Polyline. Returns true if the call is successful; 
otherwise, returns false. 


See also TDC:Polygon, TDC::PolyPolyline, TPoint 


PolylineTo 
~ bool PolylineTo(const TPoint* points, int count); 
Draws one or more connected line segments on this DC using the currently selected pen 
object. The first line is drawn from the current position to the first of the count points in 
the points array. Subsequent lines, if any, connect the remaining points in the array, with 
each end point providing the start point of the next segment. The final end point 
becomes the new current point. No filling occurs even if a closed figure i is drawn. 
‘Returns true if the call is successful; otherwise, returns false. 


Seealso TDC::PolyDraw, TDC::LineTo, TPoint class 


PolyPolygon 

bool PolyPolygon(const TPoint* points, const int* PolyCounts, int count): 

Using the current pen and polygon-filling mode, draws and fills on this DC the number 
of closed polygons indicated in count (which must be >= 2). The polygons can overlap. 
The points array specifies the vertices of the polygons to be drawn. PolyCounts is an array 
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of count integers specifying the number of vertices in each polygon. Each polygon must 
be a closed polygon. The current position is neither used nor altered by Polygon. Returns 
true if the call is successful; otherwise, returns false. 


Seealso TDC::PolyPolyline, TDC::SetPolyFillMode, TDC::GetPolyFillMode, TPoint 
class 


PolyPolyline 

bool PolyPolyline(const TPoint* points, const int* PolyCounts, int count); 

Using the currently selected pen object, draws on this DC the number of polylines 
(connected line segments) indicated in count. The resulting figures are not filled. The 
PolyCounts array provides count integers specifying the number of points (>= 2) in each 
polyline. The points array provides, consecutively, each of the points to be connected. 
Returns true if the call is successful; otherwise, returns false. The current position is 
neither used nor altered by this call. 


Seealso TDC::Polyline, TDC::PolyPolygon, TPoint class 


PtVisible 

bool PtVisible(const TPoint& point) const; 

Returns true if the given point lies within the clipping region of this DC; otherwise, 
returns false. 


Seealso TDC::RectVisible, TPoint class 


RealizePalette 

int RealizePalette(); 

Maps to the system palette the logical palette entries selected into this DC. Returns the 
number of entries in the logical palette that were mapped to the system palette. 


Seealso TPalette class 


Rectangle 

bool Rectangle(int x1, int y1, int x2, int y2); 

bool Rectangle(const TPoint& p1, const TPoint& p2); 

bool Rectangle(const TPoint& point, const TSizeé s); 

bool Rectangle(const TRect& rect); | 

Draws and fills a rectangle of the given size on this DC with the current pen and brush 
objects. The current position is neither used nor altered by this call. Returns true if the 
call is successful; otherwise, returns false. 


Seealso TDC::RoundRect, TPoint class, TRect class, TSize class 


RectVisible 

bool RectVisible(const TRect& rect) const; 

Returns true if any part of the given rectangle, rect, lies within the clipping region of this 
DC; otherwise, returns false. 


Seealso TDC::PtVisible, TRect class 
ResetDC 
virtual bool ResetDC(DEVMODE far& devMode); 


Updates this DC using data in the given devMode structure. Returns true if the call is 
successful; otherwise, returns false. 
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See also DEVMODE struct 


RestoreBrush 
void RestoreBrush(); 
Restores the original GDI brush object to this DC. 


Seealso TDC::OrgBrush, TBrush class © 


RestoreDC ; 
virtual bool RestoreDC(int savedDC = —1); 


Restores the given savedDC. Returns true if the context is successfully restored; 


otherwise, returns false. 
See also TDC::SaveDC 
RestoreFont 


virtual void RestoreFont(); | 
Restores the original GDI font object to this DC. 


Seealso TDC::OrgFont, TFont class 


RestoreObjects 
void RestoreObjects(); 
Restores all the original GDI objects to this DC. 


Seealso TGdiObject class 
RestorePalette 


void RestorePalette(); 
Restores the original GDI palette object to this DC. 


- Seealso TDC::OrgPalette, TPalette class 


a 


RestorePen 
void RestorePen(); | 
Restores the original GDI pen object to this DC. 


Seealso TDC::OrgPen, TPen class 


RestoreTextBrush 
void RestoreTextBrush(); 
Restores the original GDI text cach object to this DC. 


Seealso TBrush class 


RoundRect 

bool RoundRect(int x1, int y1, int x2, int y2, int x3, int y3); 

bool RoundRect(const TPoint& p1, const TPoint& p2, const TPoint& rad); 

bool RoundRect(const TPoint& p, const TSize& s, const TPoint& rad); 

bool RoundRect(const TRecté& rect, const TPoint& rad); | 

Draws and fills a rounded rectangle of the given size on this DC with the current pen 
and brush objects. The current position is neither used nor altered by this call. Returns 
true if the call is successful; otherwise, returns false. 


Seealso T’DC::Rectangle, TPoint class, TRect class, TSize class 
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SaveDC 

virtual int SaveDC() const; 

Saves the current state of this DC on a context stack. The saved state can be restored later 
with RestoreDC. Returns a value specifying the saved DC or 0 if the call fails. 


Seealso TDC::RestoreDC 
ScaleViewportExt 
virtual bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0); 


Modifies this DC's viewport extents relative to the current values. The new extents are 
derived as follows: 


xNewVE = (xO1dVE * xNum)/ xDenom 
yNewVE = (I * yNum)/ yDenom 


The previous extents are saved in oldExtent. Returns true if the call is successful; 
otherwise, returns false. 


Seealso TDC::SetViewportExt, TSize cass 


ScaleWindowExt 


_ virtual bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0); 


Modifies this DC's window extents relative to the current values. The new extents are 
derived as follows: 


XNewWE = (xOldWE * xNum)/ xDenom 
yNewWE = (yOldWE * yNum)/ yDenom 


The previous extents are saved in oldExtent. Returns true if the call is successful; 
otherwise, returns false. 


Seealso TDC::SetWindowExt, TSize 


ScrollIDC 
bool ScrollDC(int x, int y, const TRect& scroll, const TRect& clip, TRegion& updateRgn, TRect& updateRect); 


bool ScrollDC(const TPoint& delta, const TRect& scroll, const TRect& clip, TRegion& updateRgn, 

TRect& updateRect); 
Scrolls a rectangle of bits horizontally by x (or delta.x in the second version) device-units, 
and vertically by y (or delta.y) device-units on this DC. The scrolling and clipping 
rectangles are specified by scroll and clip. ScrollDC provides data in the updateRgn 
argument telling you the region (not necessarily rectangular) that was uncovered by the 
scroll. Similarly, ScrollDC reports in updateRect the rectangle (in client coordinates) that 
bounds the scrolling update region. This is the largest area that requires repainting. 


Returns true if the call is successful; otherwise, returns false. 


Seealso Point class, TRect class, TRegion class 


SelectClipPath 


bool SelectClipPath(int mode); 
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Selects the current path on this DC as a clipping region, combining any existing clipping 
region using the specified mode as shown in the following table: 


RGN_AND The new clipping region includes the overlapping areas of the current PeIpRnS region 
and the current path (intersection). | 


RGN_COPY The new clipping region is the current path. 


RGN_DIFF The new clipping region includes the areas of the current clipping region with those of 
the current path excluded. 
RGN_OR The new clipping region includes the combined areas of the current clipping region 


and the current path (union). 


RGN_XOR The new clipping region includes the combined areas of the current clipping region | 
and the current path but without the overlapping areas. 


Returns true if the call is successful; otherwise, returns false. 


‘SelectClipRgn 

int SelectClipRgn(const TRegion& region); 

Selects the given region as the current clipping region : for this DC. A copy of the given 
region is used, letting you select the same region for other DC objects. The return value 
indicates the new clipping region's type as follows: 


-COMPLEXRE 
ERROR | Invalid DC. 
NULLREGION Clipping region is empty. 
SIMPLEREGION _ Clipping region has no overlapping borders. 


Seealso TDC::OffsetClipRen, TDC::GetClipBox, TRegion class 


SelectObject 

void SelectObject(const TBrush& brush); 

void SelectObject(const TPen& pen); 

virtual void SelectObject(const TFont& font); 

void SelectObject(const TPalette& palette, bool ‘eidepackoroud false); 

Selects the given GDI object into this DC. The previously selected object is saved in the 
appropriate OrgXXX protected data member. For a palette argument, if forceBackgound 
is set false (the default), the selected logical palette is a foreground palette when the 
window has input focus. If forceBackground is true, the selected palette is always a 
background palette whether the window has focus or not. 


Seealso TDC::OrgBrush, TDC::OrgFont, TDC::OrgPalette, TDC::OrgPen, 
TDC::OrgTextBrush, TBrush class, TFont class, TPalette class, TPen class, 
TMemoryDC::SelectObject 


SelectStockObject 
virtual void SelectStockObject(int index); 
Selects into the DC a predefined stock pen, brush, font, or epalene 


Seealso TPrintPreviewDC::SelectStockObject 
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SetBkColor ; 

virtual TColor SetBkColor(TColor color); 

Sets the current background color of this DC to the given color value or the nearest 
available. Returns 0x80000000 if the call fails. 


Seealso ~TDC::GetBkColor, TColor class 


SetBkMode 

int SetBkMode(int mode); 

Sets the background mode to the given mode argument, which can be either OPAQUE or 
TRANSPARENT. Returns the previous background mode. 


Seealso TDC::GetBkMode 


SetBoundsRect 

uint SetBoundsRect(TRect& bounds, uint flags); 

Controls the accumulation of bounding rectangle information for this DC. Depending 
on the value of flags, the given bounds rectangle (possibly NULL) can combine with or 
replace the existing accumulated rectangle. flags can be any appropriate combination of 
the following values: | 


TOCn ACCUM ATE (CACC S TE ee 

DCB_DISABLE Turn off bounds accumulation. 

DCB_ENABLE Turn on bounds accumulation (the default setting for bounds accumulation is 
disabled). 

DCB_RESET Set the bounding rectangle to empty. 

DCB_SET Set the bounding rectangle to bounds. 


There are two bounding-rectangle accumulations, one for Windows and one for the 
application. The Windows-accumulated bounds can be queried by an application but 
not altered. The application can both query and alter the DC's accumulated bounds. 


Seealso TDC::GetBoundsRect, TRect class 


SetBrushOrg 

bool SetBrushOrg(const TPoint& origin, TPoint* oldOrg = 0); 

Sets the origin of the currently selected brush of this DC with the given origin value. The 
previous origin is passed to oldOrg. Returns true if successful; otherwise, returns false. 


Seealso TDC::GetBrushOrg, TPoint class 


SetDIBits 
bool SetDIBits(TBitmap& bitmap, uint16 startScan, uinti16 numScans, const void HUGE* bits, 

const BITMAPINFO far& Info, uint16 usage); 
bool SetDIBits(TBitmap& Bitmap, const TDib& dib); 
The first version sets the pixels in bitmap (the given destination bitmap on this DC) from 
the source DIB (device-independent bitmap) color data found in the byte array bits and 
the BITMAPINFO structure, Info.numScan scanlines are taken from the DIB, starting at 
scanline startScan. The usage argument specifies how the bmiColors member of 
BITMAPINFO is interpreted, as explained in TDC::GetDIBits. 
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In the second version of SetDIBits, the pixels are set in n bitmap from the given source T’Dib 
_ argument. 
SetDIBits returns true if the call is successful; otherwise, it returns false. 


Seealso TDC::GetDIBits, TDC::SetDIBitsToDevice, TBitmap class, BITMAPINFO 
struct, TDib class | 


SetDIBits ToDevice 
bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, uint16 startScan, uinti6 numScans, 

const void HUGE* bits, const BITMAPINFO far& bitsInfo, uint16 usage); | 
bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, const TDib& dib); 
The first version sets the pixels in dst (the given destination rectangle on this DC) from 
the source DIB (device-independent bitmap) color data found in the byte array bits and 
the BITMAPINFO structure, bitsInfo. The DIB origin is specified by the point src. 
numScan scanlines are taken from the DIB, starting at scanline startScan. The usage 
argument determines how the bmiColors member of BITMAPINFO is interpreted, as 
explained in TDC::GetDIBits. 


In the second version of SetDIBitsToDevice, the pixels are set in dst from dib, the given 
source [Dib argument. 


SetDIBitsToDevice returns true if the call is successful; otherwise, it returns false. 
Seealso TDC::GetDIBits, TDib class, TPoint class, TRect class, BITMAPINFO struct 


SetMapMode 

virtual int SetMapMode(int mode); 

Sets the current window mapping mode of this DC to mode. Returns the previous _ 
mapping mode value. The mapping mode defines how logical coordinates are mapped 
to device coordinates. It also controls the orientation of the device's x- and y-axes. See 
TDC::GetMapMode for a complete list of mapping modes. 


Seealso TDC::GetMapMode 


SetiMapperFlags 

uint32 SetMapperFlags(uint32 flag); 

Alters the algorithm used by the font mapper when mapping logical fonts to physical 
fonts on this DC. If successful, the function sets the current font-mapping flag to flag and 
returns the previous mapping flag; otherwise GDI_ERROR is returned. The mapping 
flag determines whether the font mapper will attempt to match a font's aspect ratio to 
this DC's aspect ratio. If bit 0 of flag is set to 1, the mapper selects only matching fonts. If 
no matching fonts exist, a new aspect ratio is chosen and a font is retrieved to match this 
ratio. | 


SetMiterLimit 

bool SetMiterLimit(float newLimit, float* oldLimit = 0); 

Sets the limit of miter joins to newLimit and puts the previous value in oldLimit. Returns 
true if successful; otherwise, returns false. : 


SetPixel 
TColor SetPixel(int x, int y, TColor color); 
TColor SetPixel(const TPoint& p, TColor color); 
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Sets the color of the pixel at the given location to the given color and returns the pixel's 
previous color. 


Seealso TDC::GetPixel, TColor, TPoint 


SetPolyFillMode 

int SetPolyFillMode(int mode); 

Sets the polygon-filling mode for this DC to the given mode value, either ALTERNATE 
or WINDING. Returns the previous fill mode. 


Seealso TDC::GetPolyFillMode, TDC::Polygon 


SetROP2 

int SetROP2(int mode); 

Sets the current foreground mix mode mode of this DC to the given mode value and 
returns the previous mode. The mode argument determines how the brush, pen, and 
existing screen image combine when filling and drawing. mode can be one of the 


following values: 


'R2_BLACK 
R2_COPYPEN 
R2_ MASKNOTPEN 


R2_MASKPEN 
R2_MASKPENNOT 


R2_MERGEPEN 
R2_MERGENOTPEN 
R2_MERGEPENNOT 
R2_NOP 
R2_NOT 
R2_NOTCOPYPEN 
_R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Pixelisa 


lways binary 0. 
Pixel is the pen color. 


Pixel is a combination of the colors common to both the display and the inverse 
of the pen. 


Pixel is a combination of the colors common to both the pen and the display. 


Pixel is a combination of the colors common to both the pen and the inverse of 
the display. 


Pixel is a combination of the pen color and the display color. 

Pixel is a combination of the display color and the inverse of the pen color. 
Pixel is a combination of the pen color and the inverse of the display color. 
Pixel remains unchanged. 

Pixel is the inverse of the display color. 

Pixel is the inverse of the pen color. 

Pixel is the inverse of the R2 MASKPEN color. 

Pixel is the inverse of the R2 MERGEPEN color. 

Pixel is the inverse of the R2._XORPEN color. 

Pixel is always binary 1. 

Pixel is a combination of the colors in the pen and in the display, but not in both. 


Seealso TDC::GetROP2, TDC::GetDeviceCaps 


SetStretchBitMode 


int SetStretchBitMode(int mode); 


Sets the stretching mode of this DC to the given mode value and returns the previous 
mode. The mode argument (BLACKONWHITE, COLORONCOLOR, or - 
WHITEONBLACK) defines which scan lines or columns or both are eliminated by 
TDC::StretchBlt. 


Seealso TDC::GetStretchBltMode, TDC::StretchBlt 
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SetSystemPaletteUse 

int SetSystemPaletteUse(int usage); 

Changes the usage of this DC's system palette. The usage argument can be 
SYSPAL_NOSTATIC or SYSPAL_STATIC. Returns the previous usage value. 


Seealso TDC::GetSystemPaletteUse 


SetTextAlign 

uint SetTextAlign(uint flags); 

Sets the text-alignment flags for this DC. If successful, SetTextAlign returns the previous 
text-alignment flags; otherwise, it returns GDI_LERROR. The flag values are as listed for . 
the TDC::GetTextAlign function. The text-alignment flags determine how TDC::TextOut 
and T'DC::ExtTextOut align text strings in relation to the first character's screen position. 


Seealso TDC::GetTextAlign, TDC::TextOut, TDC::ExtTextOut 


SetTextCharacterExtra 

int Set extCharacterExtra(int extra); 

If successful, sets the current intercharacter spacing to extra, in logical units, for this DC, 
and returns the previous intercharacter spacing. Otherwise, returns 0. If the current 
mapping mode is not MM_TEXT,, the extra value is transformed and rounded to the 
nearest pixel. | 


Seealso TDC::GetTextCharacterExtra 


.SetTextColor 
virtual TColor SetTextColor(TColor color); 


Sets the current text color of this DC to the given color value. The text color aeicenines 
the color displayed by TDC::TextOut and TDC::ExtTextOut. : 


See also TDC::GetTextColor, TColor 


SetTextJustification 

bool SetTextJustification(int breakExtra, int breakCount); 

When text strings are displayed using TDC::TextOut and TDC::ExtTextOut, sets the 
number of logical units specified in breakExtra as the total extra space to be added to the 
number of break characters specified in breakCount. The extra space is distributed evenly 
between the break characters. The break character is usually ASCII 32 (space), but some 
fonts define other characters. TDC::GetTextMetrics can be used to retrieve the value of 
the break character. 


If the current mapping mode is not MM_TEXT, the extra value is transformed and 
rounded to the nearest pixel. | 


SetTextJustification returns true if the call is successful; otherwise, it returns false. 


SetViewportExt 

virtual bool SetViewportExt(const TSize& extent, TSize* oldExtent = 0); 

Sets this DC's viewport x- and y-extents to the given extent values. The previous extents 
are saved in oldExtent. Returns true if the call is successful; otherwise, returns false. The 
extent value determines the amount of stretching or compression needed in the logical 
coordinate system to fit the device coordinate system. extent also eee the relative 
orientation of the two coordinate systems. 
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See also TDC::GetViewportExt, TSize class 


SetViewportOrg 

virtual bool SetViewportOrg(const TPoint& origin, TPoint* oldOrg = 0); 

Sets this DC's viewport origin to the given origin value, and saves the previous origin in 
oldOrg. Returns true if the call is successful; otherwise, returns false. 


Seealso TDC::GetViewportOrg, TDC::OffsetViewportOrg, TPoint class 


SetWindowExt 

virtual bool SetWindowExt(const TSize& extent, TSize* oldExtent = 0); 

Sets this DC's window x- and y-extents to the given extent values. The previous extents 
are saved in oldExtent. Returns true if the call is successful; otherwise, returns false. The 
extent value determines the amount of stretching or compression needed in the logical 
coordinate system to fit the device coordinate system. extent also determines the relative 
orientation of the two coordinate systems. 


Seealso TDC::GetWindowExt, TDC::ScaleWindow Ext, TSize class 


SetWindowOrg 

bool SetWindowOrg(const TPoint& origin, TPoint* oldOrg = 0); 

Sets the origin of the window associated with this DC to the given origin value, and 
saves the previous origin in oldOrg. Returns true if the call is successful; otherwise, 
returns false. 


Seealso TDC::GetWindowOrg, TDC::OffsetWindowOrg, TPoint class 


SetWorldTransform 

bool SetWorldTransform(XFORM far& xform); 

32-bit only. Sets a two-dimensional linear transformation, given by the xform structure, 
between world space and page space for this DC. Returns true if the call is successful; 
otherwise, returns false. 


See also TDC::ModifyWorldTransform, XFORM struct 


StretchBit 

bool StretchDIBits(const TRect& dst, const TRect& src, const void HUGE* bits, const BITMAPINFO far& bitsInfo, 
uint16 usage, uint32 rop=SRCCOPY); 

bool StretchDIBits(const TRect& dst, const TRect& src, const TDib& dib, uint82 roo=SRCCOPY); 

Copies the color data from src, the source rectangle of pixels in the given DIB (device- 

independent bitmap) on this DC, to dst, the destination rectangle. The DIB bits and color 

data are specified in either the byte array bits and the BITMAPINFO structure bitsInfo or 

in the TDib object, dib. The rows and columns of color data are stretched or compressed 

to match the size of the destination rectangle. The usage argument specifies how the 

bmiColors member of BITMAPINFO is interpreted, as explained in TDC::GetDIBits The 

raster operation code, rop, specifies how the source pixels, the current brush for this DC, 

and the destination pixels are combined to produce the new image. See TDC::MaskBIt 

for a detailed list of rop codes. © 


Seealso TDC::GetDIBits, TDC::MaskBIt, TDib class, TRect class, BITMAPINFO struct 
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- StretchDIBits 
bool StretchDIBits(const TRect& dst, const TRect& src, const void HUGE* bits, const BITMAPINFO far& bitsInfo, 
uinti6 usage, uint32 rop=SRCCOPY); 
bool StretchDIBits(const TRect& dst, const TRect& src, const TDib& dib, uint32 rop= =SRCCOPY); 
Copies the color data from src, the source rectangle of pixels in the given DIB (device- _ 
independent bitmap) on this DC, to dst, the destination rectangle. The DIB bits and color 
_ data are specified in either the byte array bits and the BITMAPINFO structure bitsInfo or 
in the TDib object, dib. The rows and columns of color data are stretched or compressed 
to match the size of the destination rectangle. The usage argument specifies how the 
bmiColors member of BITMAPINFO is interpreted, as explained in TDC::GetDIBits The 
raster operation code, rop, specifies how the source pixels, the current brush for this DC, 
and the destination pixels are combined to produce the new image. See TDC: ‘MaskBlt 
for a detailed list of rop codes. 


See also TDC: :GetDIBits, TDC::MaskBlt, TDib dines TRect class, BITMAPINFO stedee 


StrokeAndFillPath 

bool StrokeAndFillPath(); 

32-bit only. Closes any open figures in the current path of this DC, strokes the outline of 
the path using the current pen, and fills its interior using the current brush and polygon 
fill mode. Returns true if the call is successful; otherwise, returns false. 


See also TDC::StrokePath, TDC::BeginPath, TDC::FillPath, TDC::EndPath, 
TDC::SetPolyFillMode, TBrush class, TPen class | 


StrokePath 
bool StrokePath(); 
32-bit only. Renders the current, closed path on this DC and uses the DC's current pen. 


See also TDC: ‘StrokeAndFillPath, TDC::BeginPath 


TabbedTextOut 
bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, const int far* positions, 
int tabOrigin); 
virtual bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, 
const int far* positions, int tabOrigin, TSize& size); 
Draws up to count characters of the given null-terminated string in the current font on 
this DC. If count is -1, the whole string is written. 


Tabs are expanded according to the given arguments. The positions array specifies 
numPositions tab stops given in device units. The tab stops must have strictly increasing 
values in the array. If numPositions and positions are both 0, tabs are expanded to eight 
times the average character width. If numPositions is 1, all tab stops are taken to be 
positions[0] apart. tabOrigin specifies the x-coordinate in eee units from which tab 
expansion will start. 


_ The p argument specifies the logical coordinates of the reference point that is used to 
align the first character depending on the current text-alignment mode. This mode can 
be inspected with TDC::GetTextAlign and changed with TDC::SetTextAlign. By default, 
the current position is neither used nor altered by TabbedTextOut. However, if the align 
mode is set to TA_UPDATECP, TabbedTextOut ignores the reference point argument(s) 
and uses/updates the current position as the reference point. 
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The size argument in the second version of TabbedTextOut reports the dimensions (size.y 
= height and size.x = width) of the string in logical units. 


TabbedTextOut returns true if the call is successful; otherwise, it returns false. 


See also TDC::TextOut, TDC::GetTextAlign, TDC::SetTextAlign, TPoint class, TSize 
class 


TextOut 

virtual bool TextOut(int x, int y, const char far* string, int count = -1); 

bool TextOut(const TPoint& p, const char far* string, int count = -1); 

Draws up to count characters of the given null-terminated string in the current font on 
this DC. If count is —1 (the default), the entire string is written. 


The (x, y) or p arguments specify the logical coordinates of the reference point that is 
used to align the first character, depending on the current text-alignment mode. This 
mode can be inspected with TDC::GetTextAlign and changed with TDC::SetTextAlign. By 
default, the current position is neither used nor altered by TextOut. However, the align 
mode can be set to TA_UPDATECP, which makes Windows use and update the current 
position. In this mode, TextOut ignores the reference poirtt argument(s). 


TextOut returns true if the call is successful; otherwise, it returns false. 
Seealso TDC::ExtTextOut, TDC::GetTextAlign, TDC::SetTextAlign, TPoint class 


TextRect 

bool TextRect(int x1, int y1, int x2, int y2); 

bool TextRect(const TRect& rect); 

bool TextRect(int x1, int y1, int x2, int y2, TColor color); 

bool TextRect(const TRect rect, TColor color); 

Fills the given rectangle, clipping any text to the rectangle. If no color argument is 
supplied, the current backgound color is used. If a color argument is supplied, that color 
is set to the current background color which is then used for filling. TextRect returns true 
if the call is successful; otherwise, it returns false. 


Seealso TDC::SetBkColor, TColor class, TRect class 


UpdateColors 

void UpdateColors(); 

Updates the client area of this DC by matching the current colors in the client area to the 
system palette on a pixel-by-pixel basis. 


WidenPath 

bool WidenPath(); 

32-bit only. Redefines the current, closed path on this DC as the area that would be. 
painted if the path were stroked with this DC's current pen. The current pen must have 
been created under the following conditions: 


If the TPen(int Style, int Width, TColor Color) constructor, or the TPen(const LOGPEN* 
LogPen) constructor is used, the width of the pen in device units must be greater than 1. 


If the TPen(uint32 PenStyle, uint32 Width, const TBrush& Brush, uint32 StyleCount, 
LPDWORD pSTyle) constructor, or the TPen(uint32 PenStyle, uint32 Width, const 


Chapter 2, ObjectWindows library reference 157 


TDC class 


Form 1 


Form 2 


‘LOGBRUSH& iogBni, uint32 SiyleCount, LPDWORD pSTyle) constructor i is used, the 
pen must be a geometric pen. 


Any Bezier curves in the path are converted to sequences of linear segments 
approximating the widened curves, so no Bezier curves remain in the path after a 
WidenPath call. | 


WidenPath returns true if the call is successful; otherwise, it returns false. 


~Seealso TDC::FlattenPath, TDC::BeginPath, TPen class 


Protected constructors 


Constructors 
TDC(); 


For use by derived classes only. Calls Init to clear the OrgXXX data members and sets 
ShouldDelete to true. 


TDC(HDC handle, TAutoDelete AutoDelete); 
For use by derived classes only. Constructs a TDC object using an existing DC handle. 
Calls Init to clear the OrgXXX data members. 


Seealso TDC::Init 


Protected data members 


| Handle 


TGdiBase::Handle; 
The handle of this DC. Uses the base class's handle (TGdiBase::Handle.) — 


See also TDC 


OrgBrush 

HBRUSH OrgBrush; 

Handle to the original GDI brush object for this DC. Holds the previous brush object 
whenever a new brush is selected with SelectObject(brush). 


~Seealso TDC::SelectObject, TBrush class . 


OrgFont 

HFONT OrgFont; 

Handle to the original GDI font object for this DC. Holds the previous font object 
whenever a new font is selected with SelectObject(font). 


Seealso TDC::SelectObject, TFont class 


OrgPalette 

HPALETTE OrgPalette; 

Handle to the original GDI palette object for this DC. Holds the previous palette object - 
whenever a new palette is selected with SelectObject(palette). 


Seealso = TDC::SelectObject, TPalette class 
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OrgPen 

HPEN OrgPen; 

Handle to the original GDI pen object for this DC. Holds the previous pen object 
whenever a new pen is selected with SelectObject(pen). 


See also TDC::SelectObject, TPen class 


OrgTextBrush 

HBRUSH OrgTextBrush 

32-bit only. The handle to the original GDI text brush object for this DC. Stores the 
previous text brush handle whenever a new brush is selected with 
SelectObject(text_brush). 


Seealso TDC::SelectObject, TBrush class 


ShouldDelete 

TGdiBase::ShouldDelete; 

Set to true if the handle for this object should be deleted by the destructor; otherwise, set 
to false. 


Protected member functions 


CheckValid 
Form 1 TGdiBase::CheckValid( uint resid=IDS_GDIFAILURE) 


Form 2 _ static void CheckValid( HANDLE handle, uint resid=IDS_GDIFAILURE) 
Both versions of CheckValid check for a valid GDI object handle. If one is not found a 


GDI exception is thrown for the given resource id. Both versions use 
TGdiBase::Check Valid. | 


GetAttributeHDC 
virtual HDC GetAttributeHDC() const; 
Returns the attributes of the DC object. 


Seealso TPrintPreviewDC::GetAttributeHDC 

GetHDC 

HDC GetHDC() const; 

Returns a handle to the DC. 

Init 

void Init(); 

Sets OrgBrush, OrgPen, OrgFont, OrgBitmap, and OrgPalette to 0, and sets ShouldDelete to 
true. This function is for internal use by the TDC constructors. 


Seealso TDC constructors, TDC::SelectObject 


TDecoratedFrame class  decframe.h 


TDecoratedFrame automatically positions its client window (you must supply a client 
window) so that it is the same size as the client rectangle. You can add additional 
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decorations like toolbars and status lines to. a window. You can create a TDecoratedF rame 
without a caption bar by clearing all of the bits in the style data member of the 
TWindowAttr structure. TDecoratedFrame is a streamable class. 


For OLE-enabled applications, use TOleFrame, which creates a decorated frame and — 
manages decorations such as toolbars for the main window of an SDI (Single Document 
Interface) OLE application. 


See also TOleFrame 
Type definitions 


TLocation | 

enum TLocation (Top, Bottom, Left, Right); 

TLocation enum describes Top, Left, Bottom, and Right positions where the decoration cé can 
be placed. Insert uses this enum to position the decoration. 


Public constructor 


Constructor | 
TDecoratedFrame(TWindow* parent, const char far *title, TWindow* clientWnd, bool trackMenuSelection = false, 
TModule* module = 0); 
Constructs a TDecoratedFrame object with the specified parent window (parent), window 
caption (title), and module ID. Sets TWindow::Attr.Title to the new title. Passes a pointer 
to the client window if one is specified. By default set to false, trackMenuSelection 
controls whether hint text appears at the bottom of the window when a menu item is 
highlighted. © 


Public member functions | 


Insert 

void Insert (TWindow& decoration, TLocation = Top); 

After you specify where the decoration should be placed, Insert adds it just above, 
below, left, or right of the client window. This process is especially important when 
there are multiple decorations. Insert looks at the decoration's Attr.Style member and 
checks the WS_VISIBLE flag to tell whether the decoration should initially be visible or 
hidden. 


To position the decoration, Insert uses TLocation enum, which describes Top, Left, Bottom, 
and Right positions where the decoration can be Bae 


PreProcessMsg__ 

bool PreProcessMsg (MSG& msg); 

Overrides the virtual function defined in TFrameWindow to give decorations an 
opportunity to perform mnemonic access preprocessing. 


Seealso TFrameWindow: ‘PreProcessMsg, TWindow: PreProcessMsg 


SetClientWindow 
TWindow* a aa ad clientWnd); 
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Overrides TFrameWindow's virtual function. Sets the client window to the specified 
window. Users are responsible for destroying the old client window if they want to 
remove it. 


Protected data members 


MenultemID 
uint MenultemID; 
Specifies the menu item ID. 


TrackMenuSelection 
bool TrackMenuSelection; | 
Specifies whether you want menu selection and help status information visible. 


Protected member functions 


EvCommand 
LRESULT EvCommand(uint Id, HWND hWndCtl, uint notifyCode); 
Automates hiding and showing of decorations. 


EvCommandEnable 
void EvCommandEnable(TCommandEnabler& ce); | | | 
Handles checking and unchecking of menu items that are associated with decorations. 


EvEnterldle 

void EvEnterldle(uint source, HWND hWndDig); — 

Responds to a window message that tells an application's main window that a dialog 
box or a menu is entering an idle state. EvEnterIdle also handles updating the status bar 
with the appropriate help message. 


EviMenuSelect | 

void EvMenuSelect(uint Menultemid, uint flags, HMENU hMenu); 

Responds to user menu selection. If Menultemld is blank, displays an empty help 
message; otherwise, it displays a help message with the specified string ID. See 
EvEnterldle for a description of how the help message is loaded. 


EvSize 
void EvSize(uint sizeType, TSize& size); 
Passes a WM_SIZE message to TLayoutWindow. 


SetupWindow 
void SetupWindow(); 
Calls TLayoutWindow::Layout to size and position the decoration. 


Seealso TFrameWindow::SetUpWindow, TWindow::SetUpWindow, 
TLayoutWindow::Layout 
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Response table entries 


EV_.WM_ENTERIDLE EvEnterldle 
EV_WM_MENUSELECT  EvMenuSelect 
EV_WM SIZE EvSize 
TDecoratedMDiFrame class © | decmdifr.h 


Derived Goa both TMDIFrame and TDecoratedFrame, TDecoratedMDIErame i is an MDI 
frame that supports decorated child windows. 


- TDecorated MDIFrame supports custom toolbars. You can insert one set of decorations 
(for example, toolbars and rulers) into a decorated frame. When a different set of tools is 
needed, you can remove the previous set and reinsert another set of decorations. 
However, be sure to remove all of the unwanted decorations from the adjusted sides 
(that is, the top, left, bottom, and right) before reinserting a new set. 


TDecoratedMD IFrame is a streamable class. 


Public constructor 


Constructor 

TDecoratedMDIFrame(const char far *title, TResld menuResld, TMDiClient aclientWnd = *new TMDIClient, 
bool trackMenuSelection = false, TModule* module = 0); 

Constructs a decorated MDI frame of the specified client window with the indicated 

menu resource ID. By default, menu hint text is not displayed. 


Protected member function 


DefWindowProc 

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM IParam); 

Overrides TWindow::DefWindowProc. If the message parameter is WM_SIZE, 
DefWindowProc returns 0; otherwise, DefWindowProc returns the result of calling 
TMDIFRame::DefWindowProc. 


Seealso TMD IFrame::DefWindowProc 


Response table entries 


The TDecoratedMDIFrame response table has no entries. 
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A DC class derived from TWindowDC, TDesktopDC provides access to the desktop 
window's client area, which is the screen behind all other windows. 


Public constructor 


Constructor 
TDesktopDC(); | 
Default constructor for TDesktopDC objects. 


TDialog class | dialog.h 


Typically used to obtain information from a user, a dialog box is a window inside of 
which other controls such as buttons and scroll bars can appear. Unlike actual child 
windows which can only be displayed in the parent window's client area, dialog boxes 
can be moved anywhere on the screen. TDialog objects represent both modal and 
modeless dialog box interface elements. (A modal dialog box disables operations in its 
parent window while it is open, and, thus, lets you function in only one window 
"mode.") 


A TDialog object has a corresponding resource definition that describes the placement 
and appearance of its controls. The identifier of this resource definition is supplied to the 
constructor of the TDialog object. A TDialog object is associated with a modal or 
modeless interface element by calling its Execute or Create member function, 
respectively. 


You can use TDialog to build an application that uses a dialog as its main window by 
constructing your dialog as a TDialog and passing it as the client of a TFrameWindow. 
Your code might look something like this: 


SetMainWindow(new TFrameWindow(0, "title" new TDialog(0, IDD_MYDIALOG)) )}; 


ObjectWindows provides three-dimensional (3-D) support for dialog boxes. If your 
application expects to use Microsoft's CTL3D DLL, you need to register your application 
by calling TApplication::EnableCtl3d. ObjectWindows will then automatically forward 
the WM_CTLCOLOR message to the CTL3D DLL. 


ObjectWindows also provides BWCC support for dialog boxes. Unless a custom 
template is specified, TDialog uses the BWCC templates. (By default, TApplication’s 
member function EnableBWCC enables BWCC support.) 


TDialog is a streamable class. 


ObjectWindows also encapsulates common dialog boxes that let the user select font, file 
name, color, print options, and so on. TCommonDialog is the parent class for this group 
of common dialog box classes. 


Chapter 2, ObjectWindows library reference 163 


TDialog elass 


Public data members 


Attr 
TDialogAttr Attr; 
Attr holds the creation attributes of the dialog box (for example, size and style). 


See also TDialogAttr 


IsModal 
bool IsModal; 
IsModal is true if the dialog box is aba and false if it is modeless. 


Public constructor and destructor 


Constructor 
TDialog(TWindow* parent, TResld resid, TModule* module = 0); 

Invokes a TWindow constructor, passing parent and module, and calls Disableaucraie 
to prevent TDialog from being automatically created and displayed along with its 
parent. TDialog then initializes Title to -1 and sets TDialogAttr.Name using the dialog 
box's integer or string resource identifier, which must correspond to a dialog resource 
definition in the resource file. Finally, it initializes TDialogAttr.Param to 0 and sets 
IsModal to false. 


Destructor 

~TDialog(); 

If Attr.Name is a string and not an integer resource identifier, this destructor frees 
memory allocated to Attr.Name, which holds the name of the dialog box. 


See also TApplication::EnableBWCC, TWindow::~TWindow, 
TWindow::DisableAutoCreate, TWindow::TWindow, TDialog::Attr 


Public member functions 


CloseWindow 

void CloseWindow/(int retValue = IDCANCEL); | 

Overrides the virtual function defined by TWindow and conditionally shuts down the 
dialog box. If the dialog box is modeless, it calls TWindow::CloseWindow. If the dialog box 
is modal, it calls CanClose. If CanClose returns true, CloseWindow calls TransferData to 
transfer dialog box data, passing it retValue. The default value of retValue is IDCANCEL. 


See also TWindow::CloseWindow 


CmCancel | 
void CmCancel(); 


Automatic response to a click on the Cancel button of the dialog box. Calls Destroy, 
passing IDCANCEL. 


Seealso TDialog::CloseWindow 
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CmOk 

void CmOK(); 

Responds to a click on the dialog box's OK button with the identifier IDOK. Calls 
CloseWindow, passing IDOK. 


Seealso TDialog::CloseWindow 


Create 

virtual bool Create(); 

Creates a modeless dialog box interface element associated with the TDialog object. 
Registers all the dialog's child windows for custom control support. Calls DoCreate to 
perform the actual creation of the dialog box. 


Create returns true if successful. If unsuccessful, Create throws a TXInvalidWindow 
exception. 


Seealso TDialog::Execute, TModule::MakeWindow, TWindow::DisableAutoCreate 


Destroy 

virtual void Destroy(int retValue = IDCANCEL); 

Destroys the interface element associated with the TDialog object. If the element is a 
modeless dialog box, Destroy calls TWindow::Destroy. If the element is a modal dialog 
box, Destroy calls EnableAutoCreate on all child windows. Then Destroy calls the _ 
Windows function ::EndDialog, passing retValue as the value returned to indicate the 
result of the dialog's execution. The default retValue is IDCANCEL. 


See also TWindow::Destroy, TWindow::EnableAutoCreate 


DialogFunction 

virtual bool DialogFunction(uint message, WPARAM wParam, LPARAM IParam);_ 

To process messages within the dialog function, your application must override this 
function. DialogFunction returns true if ~~ message is handled and false if the message 
is not handled. 


DoCreate 
virtual HWND DoCreate(); 
DoCreate is called by Create to performs the actual creation of a modeless dialog box. 


DoExecute 
virtual int DoExecute(); 
DoExecute is called by Execute to perform the actual execution of a modal dialog box. 


Seealso 'Dialog::Execute 


EvClose 
void EvClose(); 
Responds to an incoming EvClose message by shutting down the window. 


EvCtiColor 

HBRUSH EvCtlColor(HDC hDC, HWND hWndChild, uint ctlType); 

Passes the handle to the display context for the child window, the handle to the child 
window, and the default system colors to the parent window. The parent window then 
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uses the ini ae handle given in hDC to set the text and background colors of 
the child window. 


If three-dimensional (3-D) support is enabled, EvCtlColor handles the 
EV_WM_CTLCOLOR message by allowing the CTL3D DLL to process the 
WM_CTLCOLOR message in order to set the pack ground color and provide a 
background brush for the window. 


Seealso TApplication::EnableCtl3d 


EvinitDialog | 

virtual bool EvinitDialog(HWND hWndFocus); 

EvInitDialog is automatically called just ee the dialog box is displayed. It calls 
SetupWindow to perform any setup required for the dialog box or its controls. 


See also TWindow::SetupWindow 


EvPaint 

void EvPaint(); 

EvPaint calls TWindow’s general-purpose default processing function, DefaultProcessing, 
for Windows-supplied painting. 


Seealso TWindow::DefaultProcessing 


EvSetFont 
virtual void EvSetFont(HFONT hfont, bool redraw); 
Responds to a request to change a dialog's font. 


Execute 

virtual int Execute(); 

Creates and executes a modal dialog box interface element associated with the TDialog 
object. If the element is successfully associated, Execute does not return until the TDialog 
is closed. 


Execute performs the following tasks: 

1 Registers this dialog's window class and all of the dialog's child windows. 
2 Calls DoExecute to execute the dialog box. 

3 Checks for exceptions and throws a TXWindow exception if an error occurs. 


Execute returns an integer value that indicates how the user closed the modal dialog box. 
If the dialog box cannot be created, Execute returns —1. 


Seealso TModule::ExecDialog, TWindow::DisableA.utoCreate, TXWindow 


GetDefaultld 
uint GetDefaultld() const; 
Gets the default resource ID. 


GetitemHandle 
HWND GetltemHandle(int childid); 

_ Returns the dialog box control's window handle identified by the supplied ID. Because 
GetItemHandle is now obsolete, new applications should use TWindow::GetDigltem. 
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PerformDiglnit 

bool PerformDigInit(); 

Initializes the dialog box controls with the contents of RT_DLGINIT, the dialog box 
resource identifier, which describes the appearance and location of the controls (buttons, 
group boxes, and so on). Returns true if successful; otherwise, returns false. 


PreProcessMsg 

bool PreProcessMsg(MSG& msg); 

Overrides the virtual function defined by TWindow in order to perform preprocessing 
of window messages. If the child window has requested keyboard navigation, 
PreProcessMsg handles any accelerator key messages and then processes any other 
keyboard messages. 


See also TWindow::PreProcessMsg, MSG struct 


SendDigitemMsg 

uint32 SendDigltemMsg(int Childid, uint16 Msg, uint16 WParam, uint32 LParam); 

Sends a window control message, identified by Msg, to the dialog box's control 
identified by its supplied ID, ChildID. WParam and LParam become parameters in the 
control message. SendDigItemMsg returns the value returned by the control, or 0 if the 
control ID is invalid. This function is obsolete. 


SetCaption 
void SetCaption(const char far* title); 
Sets the caption of the dialog box. to the value of the title parameter. 


See also TWindow::SetCaption 


SetDefaultid 
void SetDefaultld(uint Id); 
Sets the default resource ID. 


Protected member functions 


GetClassName 

char far* GetClassName(); 

Overrides the virtual function defined in TWindow and returns the name of the dialog 
box's default Windows class, which must be used for a modal dialog box. For a 
modeless dialog box, GetClassName returns the name of the default TWindow. If BWCC 
is enabled, GetClassName returns BORDLGCLASS. 


See also TWindow::GetClassName 


GetWindowClass 

void GetWindowClass(WNDCLASS& wndClass); 

Overrides the virtual function defined in TWindow. Fills WndClass with a TDialog 
registration attributes obtained from an existing TDialog window or from BWCC if it is 
enabled. 


If the class style is registered with CS_GLOBALCLASS, you must unregister the class 
style. You can do this by turning off the style bit. For example, 
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te - 
baseclass: :GetWindowClass (wndClass) ; 


- WndClass.style &= ~CS_GLOBALCLASS: 


; 3 | 

See also TWindow::GetWindowClass, TWindow, WNDCLASS struct 
SetupWindow 

void SetupWindow(); 


Overrides the virtual function defined in TWindow. Sets up the dialog box by — 
SetCaption (sets Title) and TWindow::SetupWindow. 


If three-dimensional (3-D) support is enabled, SetupWindow calls the CTL3D DLL to 
_ register the dialog box. 


See also TCommonDialog::SetupWindow, TDialog::SetCaption, 
TWindow::SetupWindow 


Response table entries 


EV_COMMAND (IDCANCEL, CmCancel) — CmCancel 


EV_COMMAND (IDOK, CmOk) CmOk 
EV_WM_CTLCOLOR EvCtlColor 
EV_WM_CLOSE : _ EvClose 
EV_WM_PAINT _ _ EvPaint 


See also TCommonDialog 


A TDialogAttr i is used to hold a TDialog's creation attributes, which include the style, 
appearance, size, and types of controls associated with the dialog box. TDialogAttr 
contains two data members: Name (the resource id) and Param. These members contain 
user-defined data used for dialog box creation. 


Public data members 


Name 

char far* Name; 

Name holds the identifier, which can be either a string or an aieoes resource identifier, 
of the dialog box resource. - 


Param 
uint32 Param; 
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Param is used to pass initialization data to the dialog box when it is constructed. You can 
assign a value to this field in a derived class's constructor. Although any Param-type 
information passed to the dialog box can be saved as a data member, Param is especially 


useful if you want to create a dialog box that's implemented by non-ObjectWindows 


code. 


After Param is accepted it is then available in the message response functions (for 
example, EvInitDialog), associated with WM_INITDIALOG. 


Seealso TDialog::Attr 


TDib class gdiobjec.h 


Form 1 


Form 2 


Form 3 


The class TDib, derived from TGdiObject, represents GDI Device Independent Bitmap 
(DIB) objects. TDibDCs encapsulate the creation of DCs using DIB.DRV (a GDI driver 
provided with Windows MME and 3.1). DIBs have no Windows handle; they are just 
structures containing format and palette information and a collection of bits or pixels. 
TDib provides a convenient way to work with DIBs like any other GDI object. The 
memory for the DIB is in one GlobalAlloc’d unit so it can be passed to the Clipboard, OLE 
2, and so on. 


The TDib Destructor overloads the base destructor because DIBs are not real GDI 
objects. 


Type definitions 


Map 
enum Map{MapFace, MapText, MapShadow, MapHighlight, MapFrame}; 

Enumerates the values for the part of the window whose color is to be set. You can OR 
these together to control the colors used for face shading on push buttons, the color of a 
selected control button, the edge shading on push buttons, text on push buttons, the 
color of the window frame, and the background color of the various parts of a window. 
The function MapUIColors uses one of these values to map the colors of various parts of 
a window to a specified color. 


Seealso TDib::MapUIColors 


Public constructors and destructor 


Constructors 

TDib(HGLOBAL handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TDib object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 


TDib(const TClipboard& clipboard); 
Constructs a T’Dib object with a handle borrowed from the given Clipboard. 


TDib(const TDib& dib); 
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Form 4 
Form 5 
Form 6 


Form 7 


This public copy constructor creates a complete copy of the given dib object as in| 


TDib myDib = yourDib; 
TDib(int width, int height, int nColors, uint16 mode = DIB RGB COLORS); 
Creates a DIB object with the given width, height, number of colors, mode values. 


TDib(HINSTANCE instance, TResID res!D); 
Creates a DIB object from the resource with the given ID. 


TDib(const char* name); 
Creates a DIB object from the given resource file. 


TDib(const TBitmap& bitmap, const TPalette* pal = 0); 
Creates a DIB object from the given resource bitmap and palette. If i is 0 (the default), 
the default palette is used. 


Destructor 
~TDib(); 
Overrides the base destructor. 


Seealso ::GetClipboardData, ~TGdiObject, TDib::InfoFromHandle, TDib::LoadFile, 
TDib::LoadResource, TGdiObject:: Handle, TGdiObject::ShouldDelete 


Public member functions 


operator BITMAPINFO() 
operator const BITMAPINFO far*() const: 
operator BITMAPINFO far*(); 


Typecasts this DIB by returning a pointer to its bitmap information structure 
(BITMAPINEO) which contains information about this DIB's oe format and 
dimensions (size, width, height, resolution, and so on). 


~ Seealso TDib::GetInfo, BITMAPINFO struct 


operator BITMAPINFOHEADER() 

operator const BITMAPINFOHEADER far*() const; 

operator BITMAPINFOHEADER far*(); 

Typecasts this DIB by returning a pointer to its bitmap info header. 


See also TDib::GetInfoHeader, BITMAPINFOHEADER struct 


ChangeModeToPal 

bool ChangeModeToPal(const TPalette& pal); 

Converts the existing color table in place to use palette relative values. The palette that is 
passed is used as a reference. Returns true if the call is successful; otherwise returns 
false. 


Seealso TDib::;ChangeModeToRGB, TPalette::GetPaletteEntry 


ChangeModeToRGB 
bool ChangeModeToRGB(const TPalette& pal); 
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Converts the existing color table in place to use absolute RGB values. The palette that is 


passed is used as a reference. Returns true if the call is successful; otherwise returns 


false. 3 
Seealso TDib::ChangeModetoPal, TPalette::GetPaletteEntry 


FindColor 
int FindColor(TColor color); 
Returns the palette entry for the given color. 


Seealso TDib::GetColor, TColor, TDib::SetColor, TDib::MapColor 


Findindex 
int FindIndex(uint16 index); 
Returns the palette entry corresponding to the given index. 


Seealso TDib::GetIndex, TDib::SetIndex, TDib::MapIndex 


GetBits 

const void HUGE* GetBits() const; 

void HUGE* GetBits(); 

Returns the Bits data member for this DIB. 


See also TDib::Bits 


GetColor 
TColor GetColor(int entry) const; 
Returns the color for the given palette entry. 


Seealso §TDib::SetColor, TColor, TDib::FindColor, TDib::MapColor 


GetColors 

const TRgbQuad far* GetColors() const; 
TRgbQuad far* GetColors(): 

Returns the bmiColors value of this DIB. 


Seealso TRgbQuad 


Getindex 
uint16 Getindex(int entry) const; 
Returns the color index for the given palette entry. 


Seealso §TDib::SetIndex, TDib::FindIndex,, TDib::MapIndex 
Getindices 
const uint16 far* GetIndices() const; 


uint16 far* Getlndices(); 
Returns the bmiColors indexes of this DIB. 


See also TDib::GetColors 


Getinfo 
const BITMAPINFO far* Getinfo() const; 
BITMAPINFO far* Getinfo(); 
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Returns this DIB's Info field. A DIB's BITMAPINFO structure contains information about 
the dimensions and color of the DIB and specifies an array of data types that define the 
colors in the bitmap. — | 


See also TDib::Info, TDib::GetInfoHeader 


GetinfoHeader | | 

const BITMAPINFOHEADER far* GetinfoHeader() const; 

BITMAPINFOHEADER far* GetInfoHeader‘(); 

Returns this DIB's bmiHeader field of the BITMAPINFO structure contains information 
about the color and dimensions of this DIB. 


Seealso TDib::Info, TDib::GetInfo, BTIMAPINFOHEADER struct 


operator HANDLE() 
operator HANDLE() const; 
Typecasts this DIB by returning its Handle. 


See also. TGdiObject::Handle 


Height 
int Height() const; 
Returns H, this DIB's height. 


Seealso TDib::Info 


IsOK 

bool IsOK() const; 

Returns false if Info is 0, otherwise returns true. If there is a problem with the 
construction of the DIB, memory is freed and Info is set to 0. Therefore, using Info is a 
reliable way to determine if the DIB is constructed correctly. 


See also Dib constructors, TDib::Info 


IsPM 

bool IsPM() const; 

Returns true if IsCore is true; that is, if the DIB is an old-style PM DIB using core headers. 
Otherwise returns false. | | 


Seealso TDib::IsCore 


_ MapColor 
int MapColor(TColor fromColor, TColor toColor, bool doAll = false); 
Maps the fromColor to the toColor in the current palette of this DIB. 


Returns the palette entry for the given color. Returns the palette entry for the toColor 
argument. 


~Seealso TDib: GetColor, TColor, TDib::SetColor, TDib::FindColor 


Mapindex 
int Mapindex(uint16 fromindex, Word tolndex, bool doAll = false); 
Maps the fromIndex to the toIndex in the current palette of this DIB. 


Returns the palette entry for the tolndex argument. 
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Seealso TDib::FindIndex, TDib::SetIndex, TDib::GetIndex 


MapUIColors 

void MapUIColors(uint mapColors, TColor* bkColor = 0 ) 

Maps the UI colors to the value specified in the parameter, mapColors, which is one of the 
values of the Map enum. Use this function to get the colors for the face shading on 
pushbuttons, the highlighting for a selected control button, the text on pushbuttons, the 
shade of the window frame and the background color. 


Seealso ‘TDib::Map enum 


NumColors 
long NumColors() const; 
Returns NumClrs, the number of colors in this DIB's palette. 


Seealso TDib::Info 


NumScans 
uinti6é NumScans() const; 
Returns the number of scans in this DIB. 


Seealso ‘TDib::StartScan 


operator << 

TClipboard& operator <<(TClipboard& clipboard, TDib& dib); 

Writes the given dib to the given clipboard. Returns a reference to the resulting Clipboard, 
allowing the normal chaining of <<. 


Seealso Clipboard 


operator == 

bool operator ==(const TDib& other) const; 

Compares two handles and returns true if this DIB's handle equals the other (other) 
DIB's handle. 


Seealso Tdib::Handle 
SetColor 


void SetColor(int entry, TColor color); 
Sets the given color for the given palette entry. 


Seealso TDib::GetColor, TColor, TDib::MapColor, TDib::FindColor 


Setindex 
void Setindex(int entry, uint16 index); 
Sets the given index for the given entry. 


Seealso TDib::GetIndex, TDib::FindIndex, TDib::MapIndex 
Size 

TSize Size() const; 

Returns TSize(W,H), the size of this DIB. 


Seealso TDib::Info, TSize 
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StartScan | 
—_ uint16 StartScan() const; 
Returns the DIB's starting scan line. 


See also TDib::numScans > 
ToClipboard 


void ToClipboard(TClipboard& clipboard); 
Puts this DIB onto the specified Clipboard. 


Seealso TClipboard 
operator TRgbQuad() 
operator const TRgbQuad far*() const; 


operator TRgbQuad far*() const; | 
Typecasts this DIB by returning a pointer to its colors structure. 


Seealso TDib::GetColors, TRebQuad 
Usage | 


uinti6 Usage() const; 
Returns the Mode for this DIB. This value tells GDI how to treat the color table. 


Seealso TDib::Mode 


Width 
int Width() const; 
Returns W, the DIB width. 


Seealso TDib::Info 


WriteFile 
bool WriteFile(const char* filename); 
Returns true if the call is successful; otherwise returns false. 


Protected data members 


Bits 
void HUGE* Bits; 
Bits points into the block of memory pointed to by Info. 


Seealso ‘TDib::GetBits 


H 
int H; 
The height of this DIB in pixels. 


Seealso TDib::Height, TDib::Size, TDib:: NumScans 


Info. 
BITMAPINFO far* Info; 
Locked global allocated block. 


Seealso TDib::GetInfo 
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IsCore 
bool IsCore; 
Set true if this DIB is an old-style PM DIB using core headers; otherwise, set false. 


See also TDib::isPM 


isResHandle 
bool IsResHandle; 
Set true if this DIB is using a resource handle; otherwise, set false. 


Mode 

uinti6 Mode; 

If Mode is DIB_RGB_Colors, the color table contains 4-byte RGB entries. If Mode is 
DIB_PAL_COLORS, the color table contains 2-byte indexes into some other palette (such 
as the system palette). Because either of these two cases might exist, two versions of 
certain functions (such as GetColors and GetIndices) are required. 


Seealso TDib::GetColors, TDib::GetIndices, TDib::Usage 


NumClirs 
long NumClrs; 
The number of colors associated with this DIB. 


Seealso TDib::NumColors 

W 

int W; 

The width of this DIB in pixels. 


Seealso [Dib::Width, TDib::Size 


Protected member functions 


InfoFromHandle 

void InfoFromHandle(); | 

Locks this DIB's handle and extracts the remaining data member values from the DIB 
header. 


Seealso TDib::GetInfoHeader 


~ LoadFile 


bool LoadFile(const char* name); 
Loads this DIB from the given file name. Returns true if the call is successful; otherwise 
returns false. 


Seealso TDib::LoadResource, TDib constructors 


LoadResource 
bool LoadResource(HINSTANCE instance, TResID res!D); 
Loads this DIB from the given resource and returns true if successful. 


Seealso TDib::LoadFile, TDib constructors 
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Read — | 

bool Read(TFile& file, long offBits = 0); 

Reads data to this DIB, starting at offset offBits, from any file, BMP, or resource. Returns 
true if the call is successful; otherwise returns false. 


Seealso § T'Dib::LoadFile 


TDibbC Class | = deh 


A DC class derived from TDC, TDibDC provides access to o device-independent bitmaps 
(DIBs). 


| Public constructors 


Constructor 
TDibDC(const TDib& dib); 
Creates a TDibDC object with the data provided i the given TDib object. 


See also classIDib, TDC::TDC 


TDocManager class | docmanag.h 


TDocManager creates a document manager object that manages the list of current 

documents and registered templates, handles standard file menu commands, and 

displays the user-interface for file and view selection boxes. To provide support for 

documents and views, an instance of TDocManager must be created by the application 
_ and attached to the application. 


The document manager normally handles events on behalf of the documents by using a 
response table to process the standard CM_FILENEW, CM_FILEOPEN, 
CM_FILECLOSE, CM_FILESAVE, CM_FILESAVEAS, CM_FILEREVERT, 
CM_FILEPRINT, CM_FILEPRINTERSETUP, and CM_VIEWCREATE. and 
CM_VIEWCREATE File menu commands. In response to a CM_FILENEW or a 
CM_FILEOPEN command, the document manager creates the appropriate document 
based on the user's selections. In response to the other commands, the document 
manager determines which of the open documents contains the view associated with 
the window that has focus. The menu commands are first sent to the window that is in 
focus and then through the parent window chain to the main window and finally to the 
application, which forwards the commands to the document manager. 


When you create a TDocManager or a derived class, you must specify that it has either a 
multi-document (dmMDIJ) or single-document (dmSDI) interface. In addition, if you — 
want the document manager to handle the standard file commands, you must OR 
dmMDI or dmSDI with dmMenu. | 


You can also enable or disable the document manager menu options by passing 
dmSaveEnable or dmNoRevert in the constructor. If you want to enable the File | Save 
menu option if the document is unmodified, pass the dmSaveEnable flag in the 
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constructor. To disable the "Revert to Saved" menu option, pass dmNokevert in the 
constructor. 


When the application directly creates a new document and view, it can attach the view 
to its frame window, create MDI children, float the window, or create a splitter. 
However, when the document manager creates a new document and view from the 
File | Open or File | New menu selection, the application doesn't control the process. To 
give the application control, the document manager sends messages after the new 
document and view are successfully created. Then, the application can use the 
information contained in the template to determine how to install the new document or 
view object. 


Public constructor and destructor 


Constructors 

TDocManager(int mode, TDocTemplate*& templateHead = DocTemplateStaticHead); 

Constructs a TDocManager object that supports either single (SDI) or multiple (MDI) 
open documents depending on the application. mode is set to either dmMenu, dmMDI, 
dmSDI, dmSaveEnable, or dmNoRevert. To install the standard TDocManager File menu 
commands, you must OR dmMDI or dmSDI with dmMenu. For example, 


DocManager = new TDocManager (DocMode | dmMenu) ; 


The document manager can then use its menu and response table to handle these 
events. If you do not specify the dmMenu parameter, you must provide the menu and 
functions to handle these commands. However, you can still use your application 
object's DocManager data member to access the document manager's functions. 


TDocManager(int mode, TApplication* app, TDocTemplate*& templateHead = DocTemplateStaticHead); 
The constructor performs the same operations as the first constructor. The additional 
app parameter, however, points to the application associated with this document. 


Destructor 

virtual ~T DocManager(); 

Destroys a TDocManager object removes attached documents templates. The constructor 
resets TDocTemplate::DocTemplateStaticHead so that it points to the head of the static 
template list. 


See also dmxxxx document manager mode constants 


Public data members 
DocList 


TDocument::List DocList; 
Holds the list of attached documents or 0 if no documents exist. 


Public member functions 


AttachTemplate 
void AttachTemplate(T DocTemplateé ); 
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_ Inserts a template into the chain of templates. 


CmFileClose 

_ virtual void CmFileClose(); 
Responds to a file close message. Tests to see if the document has been changed since it 
was last saved, and if not, prompts the user to confirm the save operation. 


CmFileNew 
virtual void CmFileNew(); 
Calls CreateAnyDoc with no path specified. 


Seealso T'DocManager::CreateAnyDoc, dtxxxx document template constants 


CmFileOpen 

virtual void CmFileOpen(); 

Lets the user select a registered template from the list displayed in the dialog box. Calls 
CreateAnyDoc. 


See also TDocManager::CreateAnyDoc 


CmFileRevert 

virtual void CmFileRevert(); 

Reverts to the previously saved document. Does not revert if the document has not been 
changed since last save; that is, if the document's IsDirty function returns false. 


CmFileSave 

virtual void CmFileSave(); 

Responds to a file save message. Sets doc to the current document. CmFileSave checks 
IsDirty only if the dmSaveEnable flag was not specified. Calls PostDocError with 
IDS_NOTCHANGED if dmSaveEnable was NOT specified and IsDirty returns false. 


See also IDS_xxxx Document String ID constants 


CmFileSaveAs 
virtual void CmFileSaveAs(); 


- Prompts the user to enter a new name for the document and saves the document to that 
file. | 


CmViewCreate 

virtual void CmViewCreate(); 

Creates a document view based on the view name of the current document. If more than 
one template exists for the document, Cm ViewCreateallows the user to select the type of 
view from the template list. 


CreateAnyDoc 

virtaul TDocument* CreateAnyDoc(const char far* path, long flags= 0); 

Creates a document based on the directory path and the specified template. flags, one of 

the document template constants, determines how the document template is created. If 
_ path is 0 and this is not a new document (the flag dtNewDoc is not set), it displays a 

dialog box. If path is 0, dtNewDoc is not set, and more than one template exists, it 

displays a dialog box and a list of templates. 


See also TDocTemplate::CreateDoc, dtxxxx document template constants 
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CreateAnyView 

virtual TView* CreateAnyView(TDocument& doc, long flags= 0); 

Creates a document view based on the directory path and specified template. flags, one 
of the document template constants, determines how the document template is created. 


See also TDocument, TDocTemplate::CreateView, dtxxxx document templateconstants 


CreateDoc 

TDocument* CreateDoc(TDocTemplate® tpl, const char far *, TDocument* parent, long flags = 0); 
CreateDoc creates a document based on the directory path and the specified template. 
flags contains one of the document template constants that determines how the 
documentis created. 


See also TDocument, TDocTemplate::CreateView, dtxxxx document template constants 


CreateView 
TView* CreateView(TDocument* doc); 
CreateView creates a view of the specified document. 


Seealso TDocTemplate::CreateView, dtxxxx document template constants 


Delete Template 
void DeleteTemplate(TDocTemplatea): 
Removes a template from the list of templates attached to the document. 


Seealso TDocManager::RefTemplate 


EvCanClose 

bool EvCanClose(); : 

Checks to see if all child documents can be closed before closing the current document. 
If any child returns false, returns false and aborts the process. If all children return true, 
EvCanClose calls TDocManager::FlushDoc for each document. If FlushDoc finds that the 
document is dirty, it displays a message asking the user to save the document, discard 

_ any changes, or cancel the operation. If the document is not dirty and EvCanClose 
returns true, EvCanClose returns true. 


Seealso TApplication::CanClose, TDocManager::FlushDoc 


EvPreProcessMenu 

void EvPreProcessMenu(HMENU hmenu); 

Called from MainWindow, EvPreProcessMenu loads and deletes a menu at the position 
specified by MF_POSITION or MF_POPUP. Your application can call EvPreProcessMenu 
to process the main window's menu before it is displayed. 


Seealso TApplication::PreProcessMenu 
EvWakeUp 
void EvWakeUp(); 


Used only after streaming in the doc manager, EoWakeUp allows for the windows to be 
created after the streaming has occurred. 


FindDocument | 
TDocTemplate* FindDocument(const char far* path); 
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MatchDocument returns the first souuinent whose pattern matches the given file name. af 
no document is compatible with the ee file name, or if the document is oa 
already, it returns 0. | 


Seealso TDocTemplate 


FlushDoc 

virtual bool FlushDoc(TDocument& doc); 

Updates the document with any changes ane prompts the user for confirmation of 
updates. 


Seealso T’Document 


GetApplication | 
TApplication* GetApplication(); 
Returns the current application. 


Seealso TApplication 


GetCurrentDoc 

virtual TDocument* GetCurrentDoc(); 

Calls TWindow::GetFocus to determine the window with the focus. Searches ie list of 
documents and returns the document that contains the view with the focus. Returns 0 if 
no document has a view with focus. 


See also TDocument 


GetNextTemplate 
TDocTemplate* GetNextTemplate(TDocTemplate® tpl); 
Returns the next document template. © 


Seealso TDocTemplate 


InitDoc 

TDocument* InitDoc(TDocument* doc, const char far* path, long flags) 

Initializes the documents, directory path for the document, and dtXXXX document flag 
values (such as dtNewDoc ) used to create document templates. 


See also TDocTemplate, dt Documentview Constants 


IsFlagSet 
bool IsFlagSet(int Flag); 
Returns true if the dtXxXXX document template constant specified in F td is set. 


See also dt Documentview Constants 


- MatchTemplate 
TDocTemplate* MatchTemplate(const char far* path); 

_MatchTemplate returns the first registered template whose pattern matches the given file 
name. If no template is compatible with the supplied file name, or if the template is open 
already, it returns 0. 


See also TDocTemplate 
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PostDocError 

virtual uint PostDocError(TDocument& doc, uint sid, uint choice = MB_OK); 

Displays a message box with the error message passed as a string resource ID in sid. By 
default, the message box contains either an OK pushbutton or a question mark icon. If 
an error message can't be found, PostDocError displays a "Message not found" message. 
choice can be one or more of the MB_Xxxx message style constants. This function can be 
overridden. 


See also TDocument::PostError, MB_Xxxx Message Constants 


PostEvent 

virtual void PostEvent(int id, TDocument& doc); 

If the current document changes, posts a WM_OWLDOCUMENT message to indicate a 
change in the status of the document. 


virtual void PostEvent(int id, TView& view); 
If the current view changes, posts a WM_OWLVIEW message to indicate a change in 
the status of the view. 


Seealso TDocument, TView 
Reffemplate 


void Reffemplate(TDocTemplate&); 
Adds a template to the list of ere attached to the document. 


Seealso TDocManager::UnRefTemplate, TDocTemplate 


SelectAnySave 
virtual TDocTemplate* SelectAnySave(TDocument& doc, bool samedoc = true); 
Selects a registered template to save with this document. 


Seealso TDocIemplate, [Document 


SelectSave | 
bool SelectSave(TDocument& doc); 
Prompts the user to select a file name for the document. Filters out read-only files. 


Seealso TDocTemplate::SelectSave 


UnRefTemplate 
void UnRefTemplate(TDocTemplate’); 
Removes a template to the list of templates attached to the document. 


Seealso TDocManager::Reffemplate, TDocTemplate 


Protected member functions 


SelectDocPath 
virtual int SelectDocPath(TDocTemplate* tpllist, int tplcount, char far* path, int buflen, long flags, 
bool save=false); 
Prompts the user to select one of the templates to use for the file to be opened. Returns 
the template index used for the selection or 0 if unsuccessful. For a file open operation, 


Chapter 2, ObjectWindows library reference 181 


TDocument class 


save is false. For a file save operation, save is true. This function can be overridden to 


provide a customized user-interface. 


Seealso TDocTemplate 


SelectDocType 
virtual int SelectDocType(TDocTemplate** tpllist, int ficou: 


SelectDocType, which can be overridden, lets the user select a document type from a list 
of document templates. Returns the template index used for the selection or 0 if 


unsuccessful. 


Seealso [DocTemplate 


SelectViewType 
virtual int SelectViewType(T DocTemplate** tpllist, int tolcount); 


Select ViewType, which can be overridden, lets the user select a view name for anew view 
from a list of view names. Returns the template index used for the selection or 0 if 


unsuccessful. 


See also TDocTemplate 


Response table entries 


EV_COMMAND(CM_FILECLOSE, CmFileClose) 
EV_COMMAND(CM._ FILENEW, CmFileNew) 
EV_COMMAND(CM_FILEOPEN, CmFileOpen) 
EV_COMMAND(CM_FILEREVERT, CmFileRevert) 
EV_COMMAND(CM._FILESAVE, CmFileSave) 
EV_COMMAND(CM FILESAVEAS, CmFileSaveAs) 
EV_COMMAND(CM_ VIEWCREATE, CmViewCreate) 
EV_COMMAND_ENABLE(CM_FILECLOSE, CmEnableClose) 
EV_COMMAND_ ENABLE(CM_FILENEW, CmEnableNew) 
EV_COMMAND_ENABLE(CM_FILEOPEN, CmEnableOpen) 
EV_COMMAND_ENABLE(CM_FILEREVERT, CmEnableRevert) 
EV_COMMAND _ENABLE(CM_FILESAVE, CmEnableSave) 
EV_COMMAND_ENABLE(CM_FILESAVEAS, CmEnableSaveAs) 
EV_COMMAND_ENABLE(CM_VIEWCREATE, CmEnableCreate) 
EV_WM_CANCLOSE 
EV_WM_PREPROCMENU 

- EV_WM_WAKEUP 
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CmFileClose 
CmFileNew 
CmFileOpen 
CmFileRevert 
CmFileSave 
CmFileSaveAs 
CmViewCreate 
CmEnableClose 
CmEnableNew 
CmEnableOpen 
EmEnableRevert 
CmEnableSave 
CmEnableSaveAs 


~ CmEnableCreate 


EvCanClose 


EvPreProcessMenu 


EvWakeUp 


docview.h 


An abstract base class, TDocument is the base class for all document objects and serves 
as an interface between the document, its views, and the document manager 


182 ObjectWindows Reference Guide 


TDocument class 


(TDocManager class). TDocument creates, destroys, and sends messages about the view. 
For example, if the user changes a document, TDocument tells the view that the 
document has been updated. The DEFINE_DOC_TEMPLATE_CLASS macro associates 
a document with its views. 


In order to send messages to its associated views, the document maintains a list of all the 
views existing for that document and communicates with the views using 
ObjectWindows event-handling mechanism. Rather than using the function 
SendMessage, the document accesses the view's event table. The views can update the 
document's data by calling the member functions of the particular document. Views can 
also request streams, which are constructed by the document. 


Both documents and views have lists of properties for their applications to use. When 
documents and views are created or destroyed, messages are sent to the application, 
which can then query the properties to determine how to process the document or view. 
It is the document manager's responsibility to determine if a particular view is 
appropriate for the given document. 


Because the property attribute functions are virtual, a derived class (which is called first) 
might override the properties defined in a base class. Each derived class must 
implement its own property attribute types of either string or binary data. If the derived 
class duplicates the property names of the parent class, it should provide the same 
behavior and data type as the parent. 


In order to add persistence to documents, [Document contains several virtual functions 
(for example, InStream and OutStream) that support streaming. Your derived classes 
need to override these functions in order to read and write data. 


Although documents are usually associated with files, they do not necessarily have to 
be files; they can also consist of database tables, mail systems, fax or modem 
transmissions, disk directories, and so on. 


Public data members 


ChildDoc 
List ChildDoc; 
The list of child documents associated with this document. 


Tag 

void far* Tag; 

Tag holds a pointer to the application-defined data. Typically, you can use Tag to install 
a pointer to your own application's associated data structure. Tag, which is initialized to 
0 at the time a TDocument is constructed, is not used otherwise by the document view 
classes. 


Type definition 


TDocProp 
enum TDocProp{ PrevProperty = 0, DocumentClass, TemplateName, ViewCount, StoragePath, DocTitle, 
NextProperty, }; 
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These property values, defined for TDocument, are available in classes derived from 
TDocument. PrevProperty and nee are delimiters for every document's 


propery list. 


Public constructor and destructor — 


Constructor 

TDocument(TDocument* parent = 0); 

Although you don't create a TDocument object directly, you must call the constructor 
when you create a derived class. parent points to the parent of the new document. If no 
parent exists, parent is 0. | 


Destructor 

virtual ~TDocument(); 

Deletes a TDocument object. Normally, Close is called first. TDocument's destructor 
destroys all children and closes all open streams. If this is the last document that used 
the template, it closes the object's template and any associated views, deletes the object's 
stream, and removes itself from the parent's list of children if a parent exists. If there is 
no parent, it removes itself from the document manager's document list. 


Seealso TDocument::Close 


Public member functions 


CanClose 

virtual boo! CanClose(); 

Checks to see if all child documents can be closed before closing the current document. 
If any child returns false, CanClose returns false and aborts the process. If all children 
return true, calls TDocManager::FlushDoc. If FlushDoc finds that the document has been 
changed but not saved, it displays a message asking the user to either save the 
document, discard any changes, or cancel the operation. If the document has not been 
changed and all children's CanClose functions return true, this CanClose function returns 
true. 


Seealso TDocManager::FlushDoc 


Close | 

virtual bool Close(); 

Closes the document but does not delete or detach the document. Before closing the 

document, Close checks any child documents and tries to close them before closing the 
parent document. Even if you write your own Close function, call TDocument's version 
so that all child documents are checked before the parent document is closed. — 


Commit 
virtual bool Commit(bool force = false); 

_ Saves the current data to storage. When a file is closed, the document manager calls 
either Commit or Revert. If force is true, all data is written to storage. TDocument's Commit 
checks any child documents and commits their changes to storage also. Before the 
current data is saved, all child documents must return true. If all child documents return 
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true, Commit flushes the views for operations that occurred since the last time the view 
was checked. Once all data for the document is updated and saved, Commit returns true. 


Seealso TDocument::Revert 


FindProperty 

virtual int FindProperty(const char far* name); 

Gets the property index, given the property name (name). Returns the integer index 
number that corresponds to the name or 0 if the name isn't found in the list of 
properties. 


Seealso § pfxxxx property attribute constants, TDocument::PropertyName 


GetDocManager 
TDocManager& GetDocManager(); 
Returns a pointer to the current document manager. 


GetDocPath 
const char far* GetDocPath(); 
Returns the directory path for the document. This might change the SaveAs operation. 


GetOpenMode 
int GetOpenMode; 
Gets the mode and protection flag values for the current document. 


See also TDocument::SetOpenMode 


GetParentDoc 

TDocument* GetParentDoc(): 

Returns the parent document of the current document or 0 if there is no parent 
document. 


GetProperty 

virtual int GetProperty(int index, void far* dest, int textlen=0); 

Returns the total number of properties for this document where index is the property 
index, dest contains the property data, and textlen is the size of the array. If textlen is 0, 
property data is returned as binary data; otherwise, property data is returned as text 

data. 


See also pfxxxx property attribute constants, TDocument::SetProperty 


GetTemplate 

TDocTemplate* GetTemplate(); 

Gets the template used for document creation. The template can be changed during a 
SaveAs operation. 


GetTitle 
CONST CHAR FAR* Gettitle(); 
Returns the title of the document. 


HasFocus 
bool HasFocus(HWND hwnd); 
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Used by the document manager, HasFocus returns true if this document's view has 
focus. hwnd is a handle to the document to determine if the document contains a view 
with a focus. 


The view associated with this ee is the active view. 


InitDoc 
virtual bool InitDoc(); 
TDocument's InitDoc is a virtual method that is overridden by TOleDocument's InitDoc. 
_ You can use this function to prepare the document before the dnCreate event, which 
indicates that the document has been created, is posted and before the view is 
_constructed. 


See also TOleDocument::InitDoc, smo document message enum 


InStream 

virtual TinStream* InStream(int mode, const char far* strmld=0); 

Generic input for the particular storage medium, InStream returns a pointer to a 
TInStream. mode is a combination of the ios bits defined in iostream.h. See the document 
open mode constants for a list of the open modes. Used for documents that support 
named streams, strmld is a pointer to the name of a stream. Override this function to 
provide streaming for your document class. 


See also TDocument::OutStream 


IsDirty 
virtual: bool -IsDirty(); | 
Returns true if the document or one of its views has changed but has not been saved. 


IsEmbedded 
virtual bool IsEmbedded(); 
Returns true if the document is embedded in an OLE2 container. 


See also TDocument::SetEmbedded 


IsOpen 

virtual bool IsOpen(); 

Checks to see if the document has any streams in its stream list. Returns false if no 
streams are open; otherwise, returns true. 


NextStream 7 
TStream* NextStream(const TStream* strm); 
Gets the next entry in the stream. Holds 0 if none exists. 


NextView 
TView* NextView(const TView* view); 
Gets the next view in the list of views. Holds 0 if none exists. 


NotifyViews 

bool NotifyViews(int event, long item=0, TView* exclude=0); 

Notifies the views of the current document and the views of any child documents of a 
change, In contrast to QueryViews, Notify Views sends notification of an event to all views 
and returns true if any views returned a true result. The event, EV_OWLNOTIPY, is 
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sent with an event code, which is private to the particular document and view class, and 
a long argument, which can be cast appropriately to the actual type passed in the 
argument of the response function. 


See also T’Document::Query Views 


Open 

virtual bool Open(int mode, const char far* path = 0); 

Opens the document using the path specified by DocPath. Sets OpenMode to mode. 
TDocument's version always returns true and actually performs no actions. Other classes 
override this function to open specified file documents and views. 


Seealso T'FileDocument::Open 


OutStream 

virtual TOutStream* OutStream(int mode, const char far* strmld = 0); 

Generic output for the particular storage medium, OutStream returns a pointer to a 
TOutStream. mode is a combination of the ios bits defined in iostream.h. Used for 
documents that support named streams, strmld points to the name of the stream. 
TDocument's version always returns 0. Override this function to provide streaming for 
your document class. 


Seealso TDocument::InStream 


PostError 

virtual uint PostError(uint sid, uint choice = MB OK); 

Posts the error message passed as a string resource ID in sid. choice is one or more of the 
MB_Xxxx style constants. 


Seealso TDocManager::PostDocError, MB_Xxxx message constants 


PropertyCount 
virtual int PropertyCount(); 
Gets the total number of properties for the TDocument object. Returns NextProperty —1. 


See also pfxxxx property attribute constants 
PropertyFlags 
virtual int PropertyFlags(int index); 


Returns the attributes of a specified property given the index (index) of the property 
whose attributes you want to retrieve. 


Seealso pfxxxx property attribute constants, TDocument::FindProperty, 
TDocument::Property Name 


PropertyName 
virtual const char* PropertyName(int index); 
Returns the name of the property given the index value (index). 


See also pfxxxx property attribute constants, TDocument::FindProperty 


QueryViews 
TView* QueryViews(int event, long item=0, TView* exclude=0); 
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Queries the views of the current document and the views of any child documents about 
_ aspecified event, but stops at the first view that returns true, In contrast to NotifyViews, 
QueryViews returns a pointer to the first view that responded to an event with a true 
result. The event, EV_OWLNOTIPY, is sent with an event code (which is private to the 
particular document and view class) and a long argument (which can be cast 
appropriately to the actual type passed in the argument of the response function). 


See also TDocument::Notify Views 


Revert 

virtual bool Revert( bool ne = false); 

Performs the reverse of Commit and cancels any changes made to the document since 
the last commit. If clear is true, data is not reloaded for views. Revert also checks all child 
documents and cancels any changes if all children return true. When a file is closed, the 
document manager calls either Commit or Revert. Returns true if the operation 1 is 
successful. 


See also  TDocument::Commit 


RootDocument 
virtual TDocument& RootDocument(); | 
Returns the this pointer as the root document. 


SetDocManager 
void SetDocManager(TDocManager& dm); 
Sets the current document manager to the argument dm. 


SetDocPath 
virtual boo! SetDocPath(const char far* path); 
Sets the document path for Open and Save operations. 


‘SetEmbedded 

virtual bool SetEmbedded(); 

SetEmbedded marks the document as being embedded in an OLE2 container. Typically, 
this happens when the server is created and when the factory template class create the 
component. 


See also TDocument::IsEmbedded 
SetOpenMode 


void SetOpenMode(int mode); 
Sets the mode and protection flag valuies for the current document. 


See also TDocument::GetOpenMode 


SetProperty 

virtual bool SetProperty(int index, const void far* src); 

Sets the value of the property, given index, the index value of the ee and src, the 
data type (either binary or text) to which the property must be set. 


See also pfxxxx property attribute constants, TDocument::GetProperty 
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SetTemplate 

bool SetTemplate(TDocTemplate* tpl): 

Sets the document template. However, if the template type is incompatible with the file, 
the document manager will refuse to save the file as this template type. 


SetTitle 
virtual void SetTitle(const char far* title); 
Sets the title of the document. - 


Protected data members 


DirtyFlag 

bool DirtyFlag; 

Indicates that unsaved changes have been made to the document. Views can also 
independently maintain their local disk status. 


Embedded 
bool Embedded; 
Indicates whether the document is embedded. 


Protected member functions 


AttachStream 

virtual void AttachStream(TStream& strm); 

Called from TStream's constructor, AttachStream attaches a stream to the current 
document. | 


DetachStream 

virtual void DetachStream(TStream& strm); | 

Called from TStream's destructor, DetachStream detaches the stream from the current 
document. 


TDocument::List class | docview.h 


The TDocument::List nested class encapsulates the chain of documents. It allows 
addition, removal, and destruction of documents from the document list. 


Public constructor and destructor 


Constructor 
List(); 
Constructs a TDocument::List object. 


Destructor 
~List(); 
Destroys the TDocument::List object. 
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Public member functions | 


Destroy 
_ void Destroy(); 
Deletes all documents. 


Insert — 
bool Insert(TDocument* doc); | 
Inserts a new document into the document list. Fails if the document already exists. 


Next — 
TDocument* Next(const TDocument* doc); 
If the doc parameter is 0, Next returns the first document in the list of documents. 


Remove 
bool Remove(TDocument* doc); 
Removes a document from the document list. 


TEdgeConstraint adds member functions that set edge (but not size) constraints. 
TEdgeConstraint always places your window one pixel above the other window and 
then adds margins. . 


For example, if the margin is 4, TEdgeConstraint places your window 5 pixels above the 
other window. The margin, which does not need to be measured in pixels, is defined 
using the units specified by the constraint. Therefore, if the margin is specified as 8 
layout units (which are then converted to 12 pixels), your window would be placed 13 
pixels above the other window. 


See also 
TLayoutConstraint struct, TEdgeOrSizeConstraint struct, TLayoutWindow (layout 
constraints example) 


Public member functions 


Above 

void Above (TWindow ‘sibling, int margin = 0) 

Positions your window above a sibling window. You must specify the sibling window 
and an optional margin between the two windows. If no margin is specified, Above sets 
the bottom of one window one pixel above the top of the other window. 


See also TEdgeConstraint::Below 


Absolute | 
void Absolute (TEdge edge, int value) 
Sets an edge of your window to a fixed value. 


Seealso TEdgeConstraint::PercentOf, TEdgeOrSizeConstraint::Absolute 
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Below 

void Below(TWindow *sibling, int margin = 0); 

Positions your window with respect to a sibling window. You must specify the sibling 
window and an optional margin between the two windows. If no margin is specified, 
Below sets the top of one window one pixel below the bottom of the other window. 


See also TEdgeConstraint::Above 


LeftOf 

void LeftOf (TWindow ‘sibling, int margin = 0) 

Positions one window with respect to a sibling window. You can specify the sibling 
window and an optional margin between the two windows. 


Seealso TEdgeConstraint::RightOf 


PercentOf 

void PercentOf (TWindow *otherWin, TEdge edge, int percent) 

Specifies that the edge of one window indicated in edge should be a percentage of the 
corresponding edge of another window (otherWin). 


Seealso TEdgeConstraint::Absolute, TEdgeOrSizeConstraint::PercentOf 


RightOf 

void RightOf (TWindow *sibling, int margin = 0) 

Positions one window with respect to a sibling window. You can specify the sibling 
window and an optional margin between the two windows. 


See also TEdgeConstraint::LeftOf 


SameAs 

void SameAs (TWindow *otherWin, TEdge edge) 

Sets the edge of your window indicated by edge equivalent to the corresponding edge of 
the window in otherWin. 


See also TEdgeConstraint::Set, TEdgeOrSizeConstraint::sameAs 


Set 

void Set(TEdge edge, TRelationship rel, TWindow *otherWin, TEdge otherEdge, int value = 0); 

Used for setting arbitrary edge constraints, Set specifies that your window's edge should 
be of a specified relationship to otherWin’s specified edge. 


Seealso TEdgeConstraint::sameAs 


_ Derived from TEdgeConstraint, TEdgeOrSizeConstraint is a template class that supports 
size constraints in addition to all the operations that TEdgeConstraint provides. The 
width or height is specified in the template instantiation of this class. There are two 
versions of each member function: one sets both edge and size constraints; the other sets 
only edge constraints. 
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Public member functions 


Absolute 
void Absolute (int value) | 
Sets the width or height of your window to a fixed value. 


void Absolute (TEdge edge, int value) 
Used to determine edge constraints only, Absolute sets the edge of your wanes toa 
fixed value. 


See also TEdgeConstraint:Absolute 
PercentOf | 


void PercentOf (TWindow *otherWin, int percent, TWidthHeight otherWidthHeight = widthOrHeight) 


Although a window's width or height defaults to being a percentage of the sibling or 
parent window's corresponding dimension, it can also be a percentage of the sibling or 
parent's opposite dimension. For example, one window's width can be 50% of the 
parent window's height. 


void PercentOf (TWindow *otherWin, TEdge edge, int percent) 

Used to determine edge constraints only, PercentOf specifies that the edge of one 
window indicated in edge should be a percentage of the corresponding edge of another 
window (otherWin. 


See also TEdgeOrSizeConstraint::Absolute, TEdgeConstraint: :PercentOf 


SameAs _ 

void SameAs (TWindow *otherWin, TWidthHeight otherWidthHeight = widthOrHeight, int value = 0) 

Although a window's width or height defaults to being the same as the sibling or parent 
window's corresponding dimension, it can be the same of the sibling's or parent's 
opposite dimension. For example, one window's width can be the same as the parent 
window's height. 


void SameAs (TWindow *otherWin, TEdge edge) 
Used to determine edge constraints only, SameAs sets the edge of one window the same 
as the corresponding edge of the other window specified in otherWin. 


Seealso TEdgeOrSizeConstraint::PercentOf, TEdgeConstraint::SameAs 


edit.h 


A TEdit is an interface object that represents an edit control interface element. A TEdit 
object must be used to create an edit control in a parent TWindow. A TEdit can be used to 
facilitate communication between your application and the edit controls of a TDialog. 
This class is streamable. : 


There are two styles of edit control opine. single-line and multiline. Multiline edit 
controls allow editing of multiple lines of text. 


The position of the first character in an edit control is zero. For a multiline edit cone 
the position numbers continue sequentially from line to line; line breaks count as two 
characters. | 
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Most of TEdit’s member functions manage the edit control's text. TEdit also includes 
some automatic member response functions that respond to selections from the edit 
control's parent window menu, including cut, copy, and paste. Two important member 
functions inherited from TEdit’s base class (TStatic) are GetText and SetText. 


Public constructors 


Constructors 

TEdit(TWindow* parent, int Id, const char far *text, int x, int y, int w, int h, uint textLen = 0, bool multiline = false, 
TModule* module = 0); 

Constructs an edit control object with a parent window (parent). Sets the creation 

attributes of the edit control and fills its Attr data members with the specified control ID 

(Id), position (x, y) relative to the origin of the parent window's client area, width (w), 

and height (/). 


If text buffer length (textLen) is 0 or 1, there is no explicit limit to the number of | 
characters that can be entered. Otherwise textLen — 1 characters can be entered. By _ 
default, initial text (text) in the edit control is left-justified «nd the edit control has a 
border. Multiline edit controls have horizontal and vertical scroll bars. 


TEdit(TWindow* parent, int resourcelD, uint textLen = 0, TModule* module = 0); 

Constructs a TEdit object to be associated with an edit control of a TDialog. Invokes the 
TStatic constructor with identical parameters. The resource[D parameter must 
correspond to an edit resource that you define. Enables the data transfer mechanism by 
calling EnableTransfer. 


Seealso TStatic::TStatic 


Public member functions 


CanUndo 
bool CanUndo(); 
Returns true if it is possible to undo the last edit. 


See also TEdit:: Undo 


Clear 
void Clear(); 
Overrides TStatic’s virtual member function and clears all text. 


ClearModify 

void ClearModify(); 

Resets the change flag of the edit control causing IsModified to return false. The flag is set 
when text is modified. 


Seealso TEdit::IsModified 
Copy 


void Copy(); 
Copies the currently selected text into the Clipboard. 
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Cut 
void Cut(); 
Deletes the scecaay selected text and copies it into the Clipboard. 


DeleteLine 
bool DeleteLine(int lineNumber); 

Deletes the text in the line specified by lineNumber in a multiline edit control. If -1_ 
passed, deletes the current line. DeleteLine does not delete the line break and affects no 
other lines. Returns true if successful. Returns false if lineNumber is not —1 and is out of 
range or if an error occurs. | 


DeleteSelection 
bool DeleteSelection(); | 
Deletes the currently selected text, and returns false if no text is selected. 


DeleteSubText 

bool DeleteSubText(uint startPos, uint endPos); 

Deletes the text between the starting and ending positions specified by startPos and 
endPos, respectively. DeleteSubText returns true if successful. 


EmptyUndoBuffer 

void EmptyUndoBuffer(); 

If an operation inside the edit control can be undone, the edit control undo flag is set. 
EmptyUndoBuffer resets or clears this flag. 


FormatLines | 

void FormatLines(bool addEOL); 

Indicates if the end-of-line characters (carriage return, linefeed) are to be added or | 
removed from text lines that are wordwrapped in a multiline edit control. Returns true 
if these characters are placed at the end of wordwrapped lines or false if they are 
removed. 


GetFirstVisibleLine | 

int GetFirstVisibleLine() const; 

Indicates the topmost visible line in an edit control. For single-line edit controls, the 
return value is 0. For multiline edit controls, the return value is the index of the topmost 
visible line. 


GetHandle 
HLOCAL GetHandle() const; 
Returns the data handle of the buffer that holds the contents of the control window. 


This function is obsolete, and is not available under Presentation Manager. 

Seealso TEdit::SetHandle | 

GetLine : 

bool GetLine(char far* str, int strSize, int lineNumber); 

Retrieves a line of text (whose line number is supplied) from the edit control and returns 


it in str (NULL-terminated). strSize indicates how many characters to retrieve. GetLine 
returns false if it is unable to retrieve the text or if the supplied buffer is too small. 
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Seealso Static::;GetText, TEdit::;GetNumLines, TEdit::GetLineLength 


GetLineFromPos 

int GetLineFromPos(uint charPos); 

From a multiline edit control, returns the line number on which the character position 
specified by charPos occurs. If charPos is greater than the position of the last character, the 
number of the last line is returned. If charPos is -1, the number of the line that contains 
the first selected character is returned. If there is no selection, the line containing the 
caret is returned. 


GetLinelndex 

uint GetLinelndex(int lineNumber); 

In a multiline edit control, GetLineIndex returns the number of characters that appear 
before the line number specified by lineNumber. If lineNumber is -1, GetLineIndex returns 
the number of the line that contains the caret is returned. 


GetLineLength 

int GetLineLength(int lineNumber); 

From a multiline edit control, GetLineLength returns the number of characters in the line 
specified by lineNumber. If it is -1, the following applies: if no text is selected, 
GetLineLength returns the length of the line where the caret is positioned; if text is 
selected on the line, GetLineLength returns the line length minus the number of selected 
characters; if selected text spans more than one line, GetLineLength returns the length of 
the lines minus the number of selected characters. 


GetNumLines 

int GetNumLines(); 

Returns the number of lines that have been entered in a multiline edit control: 1 if the 
edit control has no text (if it has one line with no text in it), or 0 if there is no text or if an 
error occurs. 


GetPasswordChar 

uint GetPasswordChar() const; | 

Returns the character to be displayed in place of a user-typed character. When the edit 
control is created with the ES_PASSWORD style specified, the default display character 
is an asterisk (*). 


See also TEdit::SetPasswordChar 


GetRect 
void GetRect(TRect& frmtRect) const; 
Gets the formatting rectangle of a multiline edit control. 


Seealso TEdit::SetRect, TEdit::SetRectNP 


GetSelection 

void GetSelection(uint& startPos, uint& endPos); 

Returns the starting (startPos) and ending (endPos) positions of the currently selected 
text. By using GetSelection in conjunction with GetSubText, you can get the currently 
selected text. 


Seealso TEdit::GetSubText 


Chapter 2, ObjectWindows library reference 195 


TEdit class 


GetSubText 
void GetSubText(char far* str, uint  startPos, uint endPos); 
Retrieves the text in an edit control from indexes startPos to endPos and returns it in str. 


Seealso TEdit::GetSelection 


GetWordBreakProc 

EDITWORDBREAKPROC GetWordBreakProc() const; 

Retrieves the current wordwrap function. Returns the address of the wordwrap 
function defined by the application or 0 if none exists. 


See also TEdit::SetWordBreakProc 


Insert 
void Insert(const char far* str); | 

Inserts the text supplied in str into the edit control at the current text insertion point 
(cursor position), and replaces any currently selected text. Insert is similar to Paste, but 
does not affect the Clipboard. 


Seealso TEdit::Paste 


IsModified 
bool IsModified(); 
Returns true if the user has changed the text in the edit control. 


Seealso J'Edit::ClearModify 


IsValid 

bool IsValid(bool reportErr = false); 

Returns true if the contents of the edit control are valid. reportErr is false so that, by 
default, IsValid doesn't bring up a system or custom message box with an error string 
created from the default string table. 


LockBuffer 
char far* LockBuffer(uint newsize=0); 
Locks the edit control's buffer and returns a pointer to the buffer. Passing newsize greater. 


than 0 causes the buffer to be resized to newsize. You must call Unlock when you are 
finished. 7 


See also TEdit:: UnLockBuffer 


Paste 

void Paste(); 

Inserts text from the Clipboard into the edit control at the current text insertion point 
(cursor position). 


Seealso TEdit::CMEditPaste 


Scroll 

void Scroll(int horizontalUnit, int verticalUnit); 

Scrolls a multiline edit control hoviventally and vertically using the numbers of 
characters specified in horizontalUnit and verticalUnit. Positive values result in scrolling 
to the right or down in the edit control, and negative values result in scrolling to the left 
or up. | 
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Search 

int Search(uint startPos, const char far* text, bool caseSensitive=false, bool wholeWord=false, bool up=false); 
Performs either a case-sensitive or case-insensitive search for the supplied text. If the 
text is found, the matching text is selected, and Search returns the position of the 
beginning of the matched text. If the text is not found in the edit control's text, Search 
returns —1. If -1 is passed as startPos, then the search starts from either the end or the 
beginning of the currently selected text, depending on the search direction. 


SetHandle 
void SetHandle(HLOCAL localMem); 
Sets a handle to the text buffer used to hold the contents of a multiline edit control. 


This function is obsolete, and is not available under Presentation Manager. 
Seealso TEdit::GetHandle 


SetPasswordChar 

void SetPasswordChar(uint ch); 

SetPasswordChar sets the character to be displayed in place of a user-typed character. 
When the ES_PASSWORD style is specified, the default display character is an asterisk 
(*). 

See also TEdit::GetPasswordChar 


SetReadOnly 
void SetReadOnly(bool readOnly); 
Sets the edit control to be read-only or read-write. 


SetRect 
void SetRect(const TRect& frmtRect); 
Sets the formatting rectangle for a multiline edit control. 


Seealso TEdit::GetRect, TEdit::SetRectNP 


-SetRectNP 

void SetRectNP(const TRect& frmtRect); 

Sets the formatting rectangle for a multiline edit control. Unlike SetRect, SetRectNP does 
not repaint the edit control. 


Seealso TEdit::GetRect, TEdit::SetRect 


SetSelection 

bool SetSelection(uint startPos, uint endPos); | 

Forces the selection of the text between the positions specified by startPos and endPos, 
but not including the character at endPos. 


SetTabStops 
void SetTabStops(int numTabs, const int far* tabs); 
Sets the tab stop positions in a multiline edit control. 


SetValidator 
void SetValidator(TValidator* validator); | 
Establishes the validator object for the edit control. 
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SetWordBreakProc 

void SetWordBreakProc(EDITWORDBREAKPROC proc); 

In a multiline edit control, SetWordBreakProc indicates that an application-supplied 
word-break function has replaced the default word-break function. The application- _ 
supplied word-break function might break the words in the text buffer at a character 
other than the default blank character. 


Seealso TEdit::;GetWordBreakProc 


Transfer 

uint Transfer(void* buffer TTransferDirection direction); 

Transfers information for TEdit controls and sends information to the Validator if one — 
exists, and if it has the transfer option set. Transfer can perform type conversion when 
validators are in place, for example, when TRangeValidator transfers integers. The return 
value is the size (in bytes) of the transfer data. 


Undo 
void Undo(); 
Undoes the last edit. 


See also TEdit::CanUndo, TEdit::;CMEditUndo 


UnlockBuffer 

void UnlockBuffer(const char far* buffer, bool updateHandle=false); 

Unlocks a locked edit control buffer. If the contents were sae cia updateHandle should 
be true. 


Seealso TEdit::LockBuffer 


ValidatorError 
void ValidatorError(); 
Handles validation errors that occur as a result of validating the edit control. 


Protected data member 


Validator 

TValidator* Validator; 

Points to the validator object constructed in your derived class to validate input text. If 
no validator exists, Validator is zero. 


Protected member functions 


CanClose 

bool CanClose(); 

Checks to see if all child windows can be closed before closing the current window. If 
any child window returns false, CanClose returns false and terminates the process. If all 
child windows can be closed, CanClose returns true. 


CmCharsEnable 
void GmCharsEnable(TCommandEnabler& commandHandler); 
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Determines whether the Clear menu item is enabled for the currently selected text. 


CmEditClear 

void CmEditClear(); 

Automatically responds to a menu selection with a menu ID of CM_EDITCLEAR by 
calling Clear. 


Seealso TStatic::Clear 


CmEditCopy 

void CmEditCopy(); 

Automatically responds to a menu selection with a menu ID of CM_EDITCOPY by 
calling Copy. 


Seealso 9 TEdit::Copy 


CmEditCut 

void CmEditCut(); 

Automatically responds to a menu selection with a menu ID of CM_EDITCUT by 
calling Cut. 


See also TEdit::Cut 


CmEditDelete 

void CmEditDelete(); _ 

Automatically responds to a menu selection with a menu ID of CM_EDITDELETE by 
calling DeleteSelection. 


See also TEdit::DeleteSelection 


CmEditPaste 

void CmEditPaste(); 

Automatically responds to a menu selection with a menu ID of CM_EDITPASTE Py 
calling Paste. 


See also TEdit::Paste 


CmEditUndo 

void CmEditUndo(); 

Automatically responds to a menu selection with a menu ID of CM_EDITUNDO by 
calling Undo. 


See also TEdit:: Undo 
CmModEnable 


void CmModEnable(TCommandEnabler& commandHandler); 
Determines whether the Undo menu item is enabled for the selected text. 


CmPasteEnable 
void CmPasteEnable(TCommandEnabler& commandHandler); 
Determines whether the Paste menu item is enabled for the selected text. 


CmSelectEnable 
void CmSelectEnable(TCommandEnabler& commiandvanclel): 


Chapter 2, ObjectWindows library reference 199 


TEdit class 


_ Determines whether the Cut, Copy, or Delete menu items are enabled for the selected 
text. _ , 

ENErrSpace | 

void ENErrSpace(); 


Sounds a beep in response to an error notification message that is sent when the edit 
control unsuccessfully attempts to allocate more memory. : 


EvChar 

void EvChar(uint key, uint repeatCount, uint flags); 

Validates the text entered into the edit control. If the input is incorrect, the original text is 
restored. Otherwise, the validated and modified text is placed back into the edit control, 
so the results of the auto-fill (if any) can be viewed. When IsValidInput is called, the 
SupressFill parameter defaults to False, so that the string can be modified. 


EvGetDigCode 

uint EvGetDigCode(MSG far* msg); | 

Responds to WM_GETDLGCODE messages that are sent to a dialog box associated 
with a control. EvGetDlgCode allows the dialog manager to intercept a message that 
would normally go to a control and then ask the control if it wants to process this 
message. If not, the dialog manager processes the message. The msg parameter indicates 
the kind of message, for example a control, command, or edit message, sent to the dialog 
box manager. 


If the edit control contains valid input, then Tabs are allowed for changing focus and a 
DLGC_WANTTABS code is returned. 


Seealso §DLGC_xxxxdialog control message constants 


EvKeyDown 

void EvKeyDown(uint key, uint repeatCount, uint flags); 

EvKeyDown translates the virtual key code into a movement. key adits the virtual 
key code of the pressed key, repeatCount holds the number of times the same key is 
pressed, flags contains one of the messages that translates to a virtual key (VK) code for 
the mode indicators. If the Tab key is sent to the Edit Control, OR 0eE checks the 
validity before allowing the focus to change. 


-EvKillFocus 
void EvKillFocus(HWND hWndGetFocus); 
In response to a WM_KILLFOCUS message sent to a window that is losing the 
keyboard, EvKillFocus hides and then destroys the caret. EvKillFocus validates text 
whenever the focus is about to be lost and holds onto the focus if the text is not valid. 
Doesn't kill the focus if another application, a Cancel button, or an OK button (in which 
case CanClose is called to validate text) has the focus. 


GetClassName | 
char far* GetClassName(); 
Returns the name of TEdit’s registration class, "EDIT." 


See also TWindow::GetClassName 
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SetupWindow 

void SetupWindow(); 

If the textLen data member is nonzero, SetupWindow limits the number of characters that 
can be entered into the edit control to textLen —1. 


Seealso TStatic::TextLen, TWindow::SetupWindow 


Response table entries 


Response table entry — er gibi nd ear a Member functio oe 
EV_COMMAND (CM _EDITCLEAR, CmEditClear) ~ CEdtClonn 
EV_COMMAND (CM_EDITCOPY, CmEditCopy) CmEditCopy 
EV_COMMAND (CM_EDITCUT, CmEditCut) CmEditCut 
EV_COMMAND (CM_EDITDELETE, CmEditDelete) CmEditClear 
EV_COMMAND (CM_EDITPASTE, CmEditPaste) CmEditPaste 
EV_COMMAND (CM_EDITUNDO, CmEditUndo) CmEditUndo 


EV_COMMAND_ENABLE(CM_EDITCLEAR, CmCharsEnable) CmCharsEnable 
EV_COMMAND_ENABLE(CM_EDITCOPY, CmSelectEnable) CmSelectEnable 
EV_COMMAND_ENABLE(CM_EDITCUT, CmSelectEnable) CmSelectEnable 
EV_COMMAND._ ENABLE(CM_EDITDELETE, CmSelectEnable) | CmSelectEnable 
EV_COMMAND._ENABLE(CM_EDITPASTE, CmPasteEnable) CmPasteEnable 
EV_COMMAND_ENABLE(CM_EDITUNDO, CmModEnable) CmModEnable 


EV_NOTIFY_AT_CHILD (EN_ERRSPACE, ENErrSpace) ENErrSpace 
EV_WM_CHAR EvChar 
EV_WM_GETDLGCODE EvGetdlgcode 
EV_WM_KEYDOWN EvKeydown 
EV_WM_KILLFOCUS EvkillFocus 
EV_WM_CHILDINVALID EvChildInvalid 
TEditFile class editfile.h 


TEditFile is a file-editing window. TEditFile’s data members and member functions 
manage the file dialog box and automatic responses for file commands such as Open, 
Read, Write, Save, and SaveAs. TEditFile is streamable. 


Public constructors and destructor 


Constructor 

TEditFile(TWindow* ()t = 0, int Id = 0, const char far* text = 0, const char far* fileName = 0, TModule* module = 0); 
Constructs a TEditFile window given the parent window, resource ID (Id), text, file 
name, and module ID. Sets Filename to fileName. 


Destructor 
~TEditFile(): | 
Frees memory allocated to hold the name of the TEditFile. 
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Public data members 


FileData | 
TOpenSaveDialog::TData FileData; 
Contains information about the user's file open or save selection. 


See also TOpenSaveDialog::TData struct 


FileName 
char far* FileName; 
Contains the name of the file being edited. 


Public member functions 


CanClear 
virtual bool CanClear(); 
Returns true if the text of the associated edit control can be cleared. 


CanClose 
virtual bool CanClose(); 
Returns true if the edit window can be closed. 


CmFileNew 

void CmFileNew(); 

Calls NewFile in response to an incoming File New command with a CM_FILENEW 
command identifier. 


Seealso TEditFile:: NewFile 


CmFileOpen 

void CmFileOpen(); 

Calls Open in response to an incoming File Open command with a CM_FILEOPEN 
command identifier. 


Seealso TEditFile::Open 


CmFileSave 

void CmFileSave(); 

Calls Save in response to an incoming File Save command with a CM_ FILESAVE 
command identifier. 


See also TEditFile::Save 


CmFileSaveAs 

void CmFileSaveAs(); 

Calls SaveAs in response to an incoming File SaveAs command with a 
CM_FILESAVEAS command identifier. 


See also TEditFile:SaveAs 


NewFile 
void NewFile(); 
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Begins the edit of a new file after calling CanClear to determine that it is safe to clear the 
text of the editor. | 


Seealso TEditFile::;CanClear 


Open 

Open(); 

Opens a new file after determining that it is OK to clear the text of the Editor. Calls 
CanClear, and if true is returned, brings up a file dialog box to retrieve the name of a new 
file from the user. Calls ReplaceWith to pass the name of the new file. 


Seealso TEditFile::CanClear, TEditFile::ReplaceWith 


Read 

bool Read(const char far* fileName=0); 

Reads the contents of a previously specified file into the Editor. Returns true if read 
operation is successful. 


ReplaceWith 

void ReplaceWith(const char far* fileName); 

Calls SetFileName and Read to replace the file currently being edited with a file whose 
name is supplied. 


Seealso TEditFile::SetFileName, TEditFile::Read 


Save 

bool Save(); 

Saves changes to the contents of the Editor to a file. If Editor->IsModified returns false, 
Save returns true, indicating there have been no changes since the last open or save. 


Seealso TEditFile::SaveAs, TEditFile::Write 


SaveAs 

bool SaveAs(); 

Saves the contents of the Editor to a file whose name is retrieved from the user, through 
execution of a File Save dialog box. If the user selects OK, SaveAs calls SetFileName and 
Write. Returns true if the file was saved. 


Seealso TEditFile::SetFileName, TEditFile::Write 
SetFileName 


void SetFileName (const char far* fileName); 
Sets FileName and updates the caption of the window. 


Write 

bool Write(const char far* fileName=0); 

Saves the contents of the Editor to a file whose name is specified by FileName. Returns 
true if the write operation is successful. 


Protected member functions 


SetupWindow 
void SetupWindow(); 
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Creates the edit window’ s Editor edit control by calling TEditFile: ‘SetupWindow. Sets the — 
window's caption to FileName, if available; otherwise sets the name to "Untitled." 


Seealso TEditFile::SetFileName, TEditFile::Read 


Response table entries 


EV_COMMAND (CM_FILENEW, CmFileNew) CmFileNew 
EV_COMMAND (CM_FILEOPEN, CmFileOpen) CmFileOpen 
EV_COMMAND (CM_FILESAVE, CmFileSave) CmFileSave 


EV_COMMAND (CM_FILESAVEAS, CmFileSaveAs) CmFileSaveAs 


TEditSearch is an edit control that responds to Find, a aoa and FindNext menu 
commands. This class is streamable. 


Public constructor 


Constructor 

TEditSearch(TWindow* parent = 0, int Id = 0, const char far* text = 0, int x = 0, int y = 0, int w = 0, inth = 0, 
TModule* module = 0); 

Constructs a TEditSearch object given the parent window, resource ID, and character 

string (text). 


Public data members 


SearchCmd 
uint SearchCmd; . 
Contains the search command identifier that opened the dialog box if one is open. 


SearchData 

TFindReplaceDialog::TData SearchData; 

The SearchData structure defines the search text string, the replacement text string, and 
the size of the text buffer. 


Seealso TFindReplaceDialog::TData 
SearchDialog 
TFindReplaceDialog* SearchDialog; 


Contains find or replace dialog-box information (such as the text to find and replace) 
and check box settings. 7 
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Public member functions 


CmEditFind 

void CmEditFind(); 

Opens a TFindDialog in response to an incoming Find command with a CM_EDITFIND 
command. 


CmEditFindNext 

void CmEditFindNext(); 

Responds to an incoming FindNext command with a CM_EDITFINDNEXT command 
identifier by calling DoSearch to repeat the search operation. 


See also TEditSearch::DoSearch 


CmEditReplace 

void CmEditReplace(); 

Opens a TReplaceDialog in response to an incoming Replace command with a 
CM_EDITREPLACE command. 


DoSearch 
void DoSearch(); 
Performs a search or replace operation base on information in SearchData. 


Seealso TFindReplaceDialog::TData 


EvFindMsg 

LRESULT EvFindMsg(WPARAM, LPARAM); 

Responds to a message sent by the modeless find or replace dialog box. Calls DoSearch 
to continue searching if text is not found or the end of the document has not been 
reached. 


Seealso TEditSearch::DoSearch 


SetupWindow 

void SetupWindow(); 

Posts a CM_EDITFIND or a CM_EDITREPLACE message to re-open a find or replace 
modeless dialog box. Calls TEdit::SetupWindow. 


Seealso TEdit::SetupWindow 
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Response table entries 


EV COMMAND(CM_EDITFIND, CmEditFind) CmEditFind 

EV COMMAND(CM_$_EDITFINDNEXT, CmEditFindNext) CmEditFindNext 
EV_COMMAND(CM._ EDITREPLACE, CmEditReplace) CmEditReplace 
EV_REGISTERED(FINDMSGSTRING, EvFindMsg) EvFindMsg 


Derived from TView and TEditSearch, TEditView provides a view wrapper for 
ObjectWindows text edit class (TEdit). A streamable class, TEditView includes several 
event-handling functions that handle messages between a document and its views. 


Public constructor and destructor 


Constructor 

TEditView(TDocument& doc, TWindow” parent = 0); 

Creates a TEditView object associated with the specified document and parent window. 
Sets AttrAccelTable to IDA_EDITVIEW to identify the edit view. Sets TView:. ‘ViewMenu 
to the new TMenuDescr for this view. 


Destructor 
~TEditView() 
Destroys a TEditView object. 


Public member functions 


CanClose 
bool CanClose(); 
Returns nonzero if the view can be closed. 


Create 

bool Create() 

Overrides TWindow::Create and calls TEditSearch::Create to create the view's window. 
Calls GetDocPath to determine if the file is new or already has data. If there is data, calls 
LoadData to add the data to the view. If the view's window can't be created, Create 
indicates the view is invalid. | : 


GetViewName 
const char far* GetViewName(); 


Overrides TView::GetViewName and returns the descriptive name of the class 
(StaticName). 


Seealso TEditView::StaticName, TView::GetViewName 
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GetWindow 
TWindow* GetWindow(); 
Get Window overrides Get Window in TView and returns this as a TWindow. 


Seealso TView::GetWindow 


PerformCreate 
void PerformCreate(int menuOrld); 


Allocates memory as necessary so that TEditView can handle files up to and including 
30,000 bytes. 


setDocTitle 

bool SetDocTitle(const char far* docname, int index) 

Overrides TView::SetDocTitle and forwards the title to its base class, TEditSearch. index is 
the number of the view displayed in the caption bar. docname is the name of the 
document displayed in the view window. 


See also TWindow::SetDocTitle, TView::SetDocTitle 


StaticName 
Static const char far* StaticName(); 
Returns "Edit View," the descriptive name of the class for the ViewSelect menu. 


Protected data member 


Origin 
long Origin; 
Holds the file position at the er of the display. 


Protected member functions 


EvNCDestroy 
void EvNCDestroy(); 
EvNcDestroy is used internally by TEditView to manage memory. 


This member is not available under Presentation Manager. 


LoadData 

boo! LoadData(); 

LoadData reads the view from the stream and closes the file. It returns nonzero if the 
view was successfully loaded. If the file can't be read, posts an error and returns 0. 


VnCommit 7 

bool VnCommit(boo! force); 

VnCommit commits changes sane in the view to the document. If force is nonzero, all 
data, even if it's unchanged, is saved to the document. 


See also TEditView::vnRevert, VNXXxx view notification constants 


VnDocClosed 
bool VnDocClosed(int omode); 
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VnDocClosed indicates that the Gocumient has been closed. mode is one of the ofxxxx 
document open constants. | 


Seealso ofxxxx document open enum, vnxxxx view notification constants 


VnisDirty 

bool VnisDirty(); 

VnIsDirty returns nonzero if changes made to the data in the view have not been saved 
to the document; otherwise, it returns 0. 


See also vnxxxx view notification constants 


VnisWindow 

bool VnisWindow(HWND hWnd); 

VnIsWindow returns nonzero if the window's handle passed in hWnd is the same as that 
of the view's display window. 


VnRevert 

bool VnRevert(bool clear); 

VnRevert is nonzero if changes made to the view should be erased, and the data from the 
document should be restored to the view. If clear is nonzero, the data is cleared instead 
of restored to the view. 


Seealso TEditView::VnCommit 


Response table entries 


EV_VN_COMMIT VnCommit 
EV_VN_DOCCLOSED — VnDocClosed 
EV_VN_ISDIRTY VulsDirty 


EV_VN_ISWINDOW VnIsWindow 
EV_WM_NCDESTROY — EvNcDestroy 
EV_VN_REVERT VnRevert 


TEqualOperator typedef eventhan.h 


typedef bool(*TEqualOperator)(TGenericTableEntry — RTFAR&, TEventinfo&); 

TEqualOperator is used to perform special kinds of searches and to faciliate finding 
response table entries. TEqualOperator compares a particular message event 
(TEventInfo&) with a response table entry Coe) to determine if they 
match. 


See also 
TResponseTableEntry 
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TEventHandler class eventhan.h 


RN teat nNOS 


TEventHandler is a base class from which you can derive classes that handle messages. 
Specifically, TEventHandler performs the following event-handling tasks: — 


1 Analyzes a window message 
2 Searches the class's response table entries for an appropriate event-handling function 
3 Dispatches the message to the designated event-handling function 


Most of ObjectWindows' classes are derived from TEventHandler and, therefore, inherit 
this event-handling behavior. In addition, any user-defined class derived from 
TEventHandler can handle message response functions that are associated with a 
particular window message. 


See also DECLARE RESPONSE_TABLE macro 


Public member functions 


Dispatch 

virtual LRESULT Dispatch(TEventInfo& WPARAM, LPARAM = 0); 

Takes the message data from TEventInfo’s Msg data member and dispatches it to the 
correct event handling function. 


Find 

virtual bool Find(TEventInfo&, TEqualOperator = 0); 

Searches the list of response table entries looking for a match. Because TEventHandler 
doesn't have any entries, TEventHandler's implementation of this routine returns false. 


Protected member function 


SearchEntries 

bool SearchEntries(TGenericTableEntry _RTFAR%* entries, TEventInfo&, TEqualOperator); 

Searches the entries in the response table for an entry that matches TEventInfo or, if so 
designated, an entry that TEqualOperator specifies is a match. 


TEventHandler::TEventinfo class eventhan.h 


A nested class, TEventInfo provides specific information about the type of message sent, 
the class that contains the function to be handled, the corresponding response table 
entry, and the dispatch function that processes the message. 


Public constructor 
Constructor 


TEventinfo(uint msg, uint id = 0) : Msg(msgq), Id(id); 
Constructs a TEventInfo object with the specified ID and message type. 
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Public data ‘iain 


Entry 
_ TGenericTableEntry _ RTFAR *Entry; 
_ Points to the response table entry (for example, EvActivate). 


Id 

const uint Id; 

Contains the menu or accelerator resource ID (CM_xxxx) for the message ee 
member function. 7 


Msg 

const uint Msg; 

Contains the type of message sent. These can be command messages, child ID messages, 
notify-based messages such as LBN_SELCHANGE, or windows messages such as 
LBUTTONDOWN. 


Object 
GENERIC *Object; | 
Points to the object that contains the function to be handled. 


-TEventStatus enum awe window.h 
TEventStatus: _ 


enum {esPartial, esComplete}; | 
Event status constants indicate the status of a mix-in window event implementation, for 
example, a keyboard event. The constants indicate whether additional handlers are 
needed. —_ 


Event status constants 


esPartial Additional handlers can be invoked. 
esComplete No additional handlers are needed. 


TFileDocument class filedoc.h 


Derived from TDocument, TFileDocument opens and closes views and provides stream 
support for views. TFileDocument has member functions that continue to process 
FileNew and FileOpen messages after a view is constructed. You can add support for 
specialized file types by deriving classes from TFileDocument. TFileDocument makes this 
process easy by hiding the actual processs of storing file types. | 
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Public constructor and destructor 


Constructor 
TFileDocument(TDocument* parent = 0); 
Constructs a TFileDocument object with the optional parent document. 


Destructor 
~TFileDocument(TDocument* parent = 0); 
Destroys a TFileDocument object. 


Type definitions 


TFileDocProp 

enum TFileDocProp {PrevProperty, CreateTime, ModifyTime, AccessTime, StorageSize, FileHandle, 
NextProperty}; 

Contains constants that define the following properties of the document: 


Niue pean ae 
PrevProperty - TDocument::NextProperty-l. This is the first value for view and document objects. 
CreateTime The time the view or document was created. 

ModifyTime The time the view or document was modified. 

AccessTime, The time the view or document was last accessed. 

StorageSize An unsigned long containing the storage size. 

FileHandle The platform file handle. 


NextProperty The is the terminating value for the property. 


Classes derived from TDocument and TView can use these generic file property values. 


Public member functions 


Close 

bool Close(); 

Closes the document but does not delete or detach any associated views. Before closing 
the document, Close calls TDocument’s Close to make sure all child documents are closed. 
If any children are open, Close returns 0 and doesn't close the document. If all children 
are closed, checks to see if any associated streams are open, and if so, returns 0 and 
doesn't close the document. If there are no open streams, closes the file. 


Seealso TDocument::Close 


Commit 

bool Commit(bool force = false); 

Calls TDocument_Commit and clears TDocument’s DirtyFlag data member, thus 
indicating that there are no unsaved changes made to the document. 


Seealso TDocument::Commit 
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Form 1 


Form 2 


FindProperty 

int FindProperty(const char far* name); 

Gets the property index, given the property name (name). Returns 0 if the name isn't 
found. 


Seealso pfxxxx property attribute constants 


GetProperty | 

int GetProperty(int index, void far* dest, int textlen=0); 

Overrides TDocument_GetProperty and gets the property ID for the current file 
document. 


See also pfxxxx property attribute constants 


InStream 

TinStream* InStream(int mode, const char far* strmld = 0); 

Overrides TDocument_InStream and provides generic input for the particular storage 
medium. InStream returns a pointer to a TInStream. mode is a combination of the ios bits 
defined in iostream.h. strmld is not used for file documents. The view reads data from 
the document as a stream or through stream functions. 


Seealso TFileDocument::OutStream 


IsOpen 
bool IsOpen(); 
Is nonzero if the document or any streams are open. 


Open 

bool Open(HFILE fhdl); 

Opens a file document using an existing file handle. Sets TDocument_OpenMode to 
PREV_OPEN and read/write. Sets the document path to 0. Sets FHd to fhdl. Always 
returns nonzero. 


bool Open(int mode, const char far* path=0); 

Overrides TDocument_Open and opens the file using the specified oath If the file is 
already open, returns 0. Calls TDocument_SetDocPath to set the directory path. If omode 
isn't 0, sets TDocument_OpenMode to omode. If the file can't be opened, returns 0. 


Seealso TDocument::SetDocPath, TDocument::Open, ofxxxx document open enum 


OutStream 

TOutStream* OutStream (int mode, const char far* strmld = 0); 

Overrides TDocument_OutStream and provides generic input for the particular storage 
medium. OutStream returns a pointer to a TOutStream. mode is a combination of the ios 
bits defined in iostream.h. strmld is not used for file documents. Instead, the view reads 
data from the document through stream functions. 


~Seealso TFileDocument::InStream 


PropertyFlags 
int PropertyFlags(int index); 
Returns the property attribute constants (pfGetText, pfHidden, and so on). 


Seealso pfxxxx property attribute constants 
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PropertyName 
const char* PropertyName(int index); 
Returns the text name of the property given the index value. 


Seealso pfxxxx property attribute constants 


Revert 

bool Revert(bool clear = false); 

Calls TDocument_Revert to notify the views to refresh their data. If clear is false, the data 
is restored instead of cleared. 


Seealso TFileDoc::Commit 
SetProperty 


bool SetProperty(int index, const void far* src); 
Sets the property data, which must be in the native data type (either string or binary). 


Seealso pfxxxx property attribute constants 


Protected data member 


FHdl 
HFILE FHdl; 
Holds the file handle to an open file document. 


Protected member functions 


CloseThisFile 

void CloseThisFile(HFILE fhdl, int omode); 

Closes the file handle if the associated file was opened by TFileDocument. Calls 
TDocument_Notify View to notify all views that the file document has closed. 


Seealso ofxxxx document open enum 


OpenrThisFile 

HFILE OpenThisFile(int omode, const char far* name, streampos* pseekpos); 

Opens the file document after checking the file sharing mode (omode). If a file mode is 
not specified as read, write, or read and write, OpenThisFile returns 0. 


Seealso ofxxxx document open enum, shxxxx document sharing modes 


TFileOpenDialog class opensave.h 


TFileOpenDialog is a modal dialog box that lets you specify the name of a file to open. 
Use this dialog box to respond to a CM_FILEOPEN command that's generated when a 
user selects File | Open from a menu. TFileOpenDialog uses the TOpenSave::TData 
structure to initialize the file open dialog box. 
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TFileSaveDialog class 


Public constructor 


Constructor 
TFileOpenDialog(TWindow* parent, TData& data, TResID templatelD = 0, const char far* title = 0, 

TModule* module = 0); 
Constructs and initializes the TF ileOpen object based on information in the : 
TOpenSaveDialog::TData data structure. The parent argument points to the dialog box's- 
parent window. data is a reference to the TData object. templateID is the ID for a custom 
template. title is an optional title. module points to the module instance. 


Seealso TOpenSaveDialog::TData, TOpenSaveDialog, TResID, TModule 


Public member function 


DoExecute 
int DoExecute(); 
Creates the TFileOpenDialog object. 


Seealso TDialog::DoExecute 


TFileSaveDialog class | opensave.h 


TFileSaveDialog is a modal dialog box that lets you enter the name of a file to save. Use 
TFileSaveDialog to respond to a CM_FILESAVEAS command generated when a user . 
selects File | Save from a menu. TFileSaveDialog uses the TOpenSave::TData structure to 
initialize the file save dialog box. 


Public constructor 


Constructor 
TFileSaveDialog(TWindow* parent, TData& data, TResID templatelD = 0, const char far* title = 0, 

TModule* module = 0); 
Constructs and initializes the TFileOpen object based on the TOpenSaveDialog::TData 
structure, which contains INIORMAHON about the file name, file directory, and file name 
search filers. | 


Seealso TOpenSaveDialog::TData structure, TModule, TResID, TWindow 


Public member function 


DoExecute 
int DoExecute(); 
Creates the TFileSaveDialog object. 


Seealso TDialog::DoExecute, TOpenSaveDialog 
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TFilterValidator class 


TFilterValidator class — validate.h 


A streamable class, TFilterValidator checks an input field as the user types into it. The 
validator holds a set of allowed characters. When the user enters a character, the filter 
validator indicates whether the character is valid or invalid. See TValidator for an 
example of an input validation screen. 


Public constructor 


Constructor 

TFilterValidator(const TCharSet& validChars); | 

Constructs a filter validator object by first calling the constructor inherited from 
TValidator, then setting ValidChars to validChars. 


Public member functions 


Error 

void Error(); 

Error overrides TValidator’s virtual function and sissies a message box indicating that 
the text string contains an invalid character. 


Seealso TValidator::Error 


IsValid 

bool IsValid(const char far* str); 

IsValid overrides TValidator’s virtuals and returns true if all characters in str are in the set 
of allowed characters, ValidChar; otherwise, it returns false. 


IsValidinput 

bool IsValidinput(char far* str, boo! suppressFill); 

IsValidInput overrides TValidator’s virtual function and checks each character in the 
string str to ensure it is in the set of allowed characters, ValidChar. Is ValidInput returns 
true if all characters in str are valid; otherwise, it returns false. 


Seealso TValidator::IsValidInput 


Protected data members 


ValidChars 

TCharSet ValidChars; 

Contains the set of all characters the user can type. For example, to allow only numeric 
digits, set ValidChars to "0-9". ValidChars is set by the validChars parameter passed to the 
constructor. 
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TFindDialog class | | | 
TFindDialog class _ —findreplh 


TFindDialog objects represents modeless dialog box interface elements that let you 
specify text to find. TFindDialog communicates with the owner window using a 
registered message. Derived from TFindReplaceDialog, TFindDialog uses the _ 
TFindReplaceDialog::TData structure to initialize ne dialog box with user-entered values 
(such as the text string to find). 


Public constructor 


Constructor | 
TFindDialog(TWindow* parent, TData& data, TResid templateld = 0, const char far* title = 0, 

TModule* module = 0); 
Constructs a TFindDialog object with the given parent window, resource ID, and 
caption. Sets the attributes of the dialog box based onT'FindReplaceDialog::TData 
structure, which contains information about the text string to search for. 


Seealso FindReplaceDialog::TData 


Protected member functions 


DoCreate 
HWND DoCreate(); 
Creates the modeless interface siemeae of a find dialog. 


TFindReplaceDialog class __findrepI.h- 


TFindReplaceDialog is an abstract base class for a modeless dialog box that lets you search 
for and replace text. This base class contains functionality common to both derived 
classes, TFindDialog which lets you specify text to find, and TReplaceDialog which lets 
you specify replacement text. TFindReplaceDialog communicates with the owner 
window using a registered message. 


Public constructor 


Constructor 
TFindReplaceDialog(TWindow* parent, TData& data, TResld templateld = 0, const char far* title = 0, 

TModule* module = 0); | 
Constructs a TFindReplaceDialog object with a parent window, resource ID, and caption. 
Sets the attributes of the dialog box with the specified data from the 
TFindReplaceDialog:: ‘TData structure. 


See also | TFindReplaceDialog::TData struct, TModule, TResID, TWindow 
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TFindReplaceDialog class 


Public member functions 


CmCancel 
void CmCancel(); 
Responds to a click of the Cancel button. 


CmFindNext 
void CmFindNext(); 
Responds to a click of the Find Next button. 


CmReplace 
void CmReplace(); 
Responds to a click of the Replace button. 


CmReplaceAll 
void CmReplaceAli{); 
Responds to a click of the Replace All button. 


EvNCDestroy 

void EvNCDestroy(); 

Calls TWindow::EvNCDestroy, which responds to an incoming EV_WM_NCDESTROY 
message which tells the owner window that is nonclient area is being destroyed. 


Protected data members 


Data 
TData& Data; 
Data is a reference to the TData object passed in the constructor. 


Seealso TFindReplaceDialog::TData class 
fr 
FINDREPLACE fr; 


A struct that contains find-and-replace attributes, such as the size of the find buffer and 
pointers to search and replace strings, used for find-and-replace operations. 


See also FINDREPLACE class 


Protected member functions 


DoCreate 

HWND DoCreate()=0; 

DoCreate is a virtual function that is overridden in derived classes to create a modeless 
find or replace dialog box. 


DialogFunction 
bool DialogFunction(uint message, WPARAM, LPARAM); 
Returns true if a message is handled. 


Seealso TDialog::DialogFunction 
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TFindReplaceDialog::TData class 


Init 

void Init(TResid templateld): 

Used by constructors in derived classes, Init initializes a TFindReplaceDialog ES with 
the current resource ID and other members. 


Response table entries 


EV_WM_NCDESTROY — EvNCDestroy 


The TFindReplaceDialog::TData class encapsulates information necessary to initialize a 
TFindReplace dialog box. The TFindDialog and TReplaceDialog classes use the 
TFindReplaceDialog::T Data class to initialize the dialog box and to accept user-entered 
options such as the search and el text strings. 


Public constructor and destructor 


Constructor 

TFindReplaceDialog(uint32 flags = 0, int bufferSize = 81); 

Constructs a TData object with the specified flag value that initializes the status of the 
dialog box control buttons and the buffer size for the find and replace search strings. 


Destructor 
~TData(); | 
Destroys a ~TData object. 


Public data members 


BuffSize 
int BuffSize; 
BuffSize contains the size of the text buffer. 


Error 

~ uint32 Error; 
If the dialog box is successfully created, Error is 0. Otherwise, it contains one or more of © 
the following error codes: 


CDERR_LOCKRESOURCEFAILURE Failed to lock a specified resource. 
~ CDERR_LOADRESFAILURE Failed to load a specified resource. 
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CDERR LO eran _ 


CDERR_REGISTERMSGFAIL 


FindWhat 
char* FindWhat; 


TFloatingFrame class 


- Failed to load z a repecified ae 


The window message (a value used to communicate between 
applications) cannot be registered. This message value is used 


when sending or posting window messages. 


Contains the search string. 


Flags 
uint32 Flags; 


Flags, which indicates the state of the control buttons and the action that occurred in the 
dialog box, can be a combination of the following constants that indicate which 
command the user wants to select: 


Constant _ : 
‘FR. DOWN 


FR_HIDEMATCHCASE 
FR_HIDEWHOLEWORD 
FR_HIDEUPDOWN. 
FR_MATCHCASE 
FR_NOMATCHCASE 


FR_NOUPDOWN 
FR_NOWHOLEWORD 


FR_REPLACE 
FR_REPLACEALL 
FR_WHOLEWORD 


ReplaceWith 
char* ReplaceWith; 


— ‘Meaning _ 


The Down buon in ithe Direction sroup of the Find fee 


box is selected. 

The Match Case check box is hidden. 
The Whole Word check box is hidden. 
The Up and Down buttons are hidden. 
The Match Case check box is checked. 


The Match Case check box is disabled. This occurs when the 
dialog box is first initialized. 

The Up and Down buttons are disabled. This occurs when the 
dialog box is first initialized. 


The Whole Word check box is disabled. This occurs when the 
dialog box is first initialized. 


The Replace button was pressed in the Replace dialog box. 


The Replace All button was pressed in the Replace dialog box. 


The Whole Word check box is checked. 


ReplaceWith contains the replacement string. 
Seealso TEditSearch::SearchData, TFindReplaceDialog::Data 


TFloatingFrame class 


floatfra.h 


Derived from TFrameWindow and TTinyCaption, TFloatingFrame implements a floating 
frame that can be positioned anywhere in the parent window. Except for the addition of 
a tiny caption bar, the default behavior of TFrameWindow and TFloatingFrame is the 
same. Therefore, an application that uses TFrameWindow can easily gain the 
functionality of TFloatingFrame by just changing the name of the class to T'FloatingFrame. 
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TFloatingFrame class 


If there is a client window, the floating frame shrinks to fit the client window, leaving 

room for margins on the top, bottom, left, and right of the frame. Because the floating 

frame expects the client window to paint its own background, it does nothing in 

response to a WM_ERASEBKGND message. However, if there is no client window, the 
_ floating frame erases the client area background using COLOR_BTNFACE. 


See PAINT.CPP, the sample program on your distribution disk, for; an a ofa 
floating frame. 


Public constructor 


Constructor _ 
TFloatingFrame(TWindow *owner, char “title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, 

int CaptionHeight = DefaultCaptionHeight, bool popupPalette = false, Module* module = 0); 
Constructs a TFloatingFrame object attached to the specified parent window. By default, 
the floating frame window doesn't shrink to fit the client window, and the floating 
palette style isn't enabled. 


Set popupPalette to true if you want to enable a floating palette style for the window. The 
floating palette is a popup window with a tiny caption, a standard window border, and 
a close box instead of a system menu box. There are no maximize or minimize buttons. 
A one pixel border is added around the client area in case a toolbox is implemented. 
This style must be turned on before the window is created. After the window is created, 
its style can't be changed. 


Seealso 9 TFrameWindow::TFrameWindow, TTinyCaption::TTinyCaption 


Public member functions 


SetMargins 

void SetMargins(const TSize& margin); 

Sets the margins of the floating palette window to the size specified i in sal and sets 
the height of the tiny caption bar. 


See also TTinyCaption::EnableTinyCaption 
Protected member functions 
DoNCHitTest 

TEventStatus DoNCHitTest(TPoint& screenPt, uint& evRes); 


If the floating palette is not enabled, returns esPartial. Otherwise, eae a message to the 
floating palette that the mouse or the cursor has moved, and returns esComplete. 
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Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


TFont class 


Response table entries 


EV_WM_SYSCOMMAND _— EvSysCommand 
EV_WM_NCCALCSIZE EvNCCalcSize 


EV_WM_NCPAINT EvNCPaint 
EV_WM_NCHITTEST EvNcHitTest 
TFont class gdiobjec.h 


TFont derived from TGdiObject provides constructors for creating font objects from 
explicit information or indirectly. 


Public constructors 


Constructors 

TFont(HFONT handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a T’Font object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 


TFont(const char far* facename = 0, int height = 0, int width = 0, int escapement = 0, 
int orientation = 0 int weight = FW_NORMAL, uint8 pitchAndFamily = DEFAULT _PITCH| 
FF DONTCARE, uint8 italic = false, uint8 underline = false, uint8 strikeout = false, uint8 charSet = 1, 
uint8 outputPrecision = OUT DEFAULT PRECIS, uint8 clipPrecision = CLIP_ DEFAULT PRECIS, 
uint8 quality = DEFAULT QUALITY); | 
Creates a TFont object with the given values. 
TFont(int height, int width, int escapement = 0, int orientation = 0, int weight = FW_NORMAL, uint italic = false, 
BYTE underline = false, uint8 strikeout = false, uint8 charSet = 1, uint8 outputPrecision = 
OUT_DEFAULT PRECIS, uint8 clipPrecision = CLIP_DEFAULT PRECIS, uint8 quality = 
DEFAULT QUALITY uint8 pitchAndFamily = DEFAULT PITCH| 
FF_DONTCARE, const char far* facename = 0); 
Creates a font object with the given values. The constructor parameter list and default 
values match the Windows API CreateFont call. 


TFont(const LOGFONT far* logFont); 
Creates a TFont object from the given logFont. 


TFont(const TFont& font); 
The T'Font copy constructor. 


See also ::CreateFont (Windows API), ::CreateFontIndirect (Windows API), 
TGdiObject:: Handle, TGdiObject::ShouldDelete, 
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TFrameWindow class 


Public member functions 


GetObject 

bool GetObject(LOGFONT far& logFont) const; 

Retrieves information about this pen object and places it in the given LOGFONT 
structure. Returns true if successful and false if unsuccessful. 


See also TGdiObject::GetObject, LOGFONT struct 


operator HFONT() 

operator HFONT() const; | 

Typecasting operator that converts this font's Handle to type HFONT (the data type 
representing the handle to a Payal font). 


TFrameWindow class framewin.h 


Form 1 


Derived from TWindow, TFrameWindow controls such window-specific behavior as 
keyboard navigation and command processing for client windows. For example, when 
a window is reactivated, TFrameWindow is responsible for restoring a window's input 
focus and for adding menu bar and icon support. TFrameWindow is a streamable class. 


In terms of window areas, the frame area consists of the border, system menus, toolbars 
and status bars whereas the client area excludes these areas. Although frame windows 
can support a client window, the frame window remains separate from the client 
window so that you can change the client window without affecting the frame window. 


ObjectWindows uses this frame and client structure for both TFrameWindow and 
TMDIChild classes. Both these classes can hold a client class. Having a separate class for 
the client area of the window adds more flexibility to your program. For example, this 
separate client area, which might be a dialog box, can be moved into another frame 


~ window, either a main window or an MDI child window. | 


See TFloatingFrame for a description of a floating frame with the same default 
functionality as a frame window. 


Public constructors and destructor 


Constructors 
TFrameWindow(TWindow* parent, const char far *title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, 
TModule* module = 0); 

Constructs a window object with the parent window supplied in parent, which is zero if — 
this is the main window. title, which by default is zero, contains the title displayed in the 
window's caption bar. clientWnd is the client window for this frame window or zero if 
none exists. shrinkToClient controls whether the client window will size to fit the frame 
or the frame window will fit the client. Note that this parameter only affects the size of 
the main window. When a client window is used in a frame window that doesn't have 


_ shrinktoClient set, the client window resizes to fit the frame window. When a client 


window is used in a frame window that has the shrinktoClient set, the frame window 
shrinks to fit the size of the client window. 
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Form 2 


TFrameWindow class 


TFrameWindow(HWND hWnd, TModule* module = 0); 

Constructor for a TFrameWindow that is being used as an alias for a non-ObjectWindows 
window. hWnd is the handle to the existing window object that TFrameWindow controls; 
module contains the module passed to the base class's contructor. 


Destructor 
~TFrameWindow(); 
Deletes any associated menu descriptor. 


Seealso TWindow::TWindow, TFloatingFrame::TFloatingFrame 


Public data members 


KeyboardHandling 
bool KeyboardHandling; 
Indicates if keyboard navigation is required. 


Public member functions 


AssignMenu 

virtual bool AssignMenu(TResid menuResld); 

Sets Attr.Menu to the supplied menuReslId and frees any previous strings pointed to by 
Attr.Menu. If HWindow is nonzero, loads and sets the menu of the window, destroying 
any previously existing menu. 


Seealso TMDIFrameWindow::SetMenu, TFrameWindow::SetMenuDescr 


EnableKBHandler 

void EnableKBHandler(); 

Sets a flag indicating that the receiver has requested keyboard navigation (translation of 
keyboard input into control selections). By default, the keyboard interface, which lets 
users use the Tab and arrow keys to move between the controls, is disabled for windows 
and dialog boxes. | 


GetClientWindow 

virtual TWindow* GetClientWindow(); 

Returns a pointer to the client window. If you are trying to access a window-based 
object in a TMDIChild (which is a frame window), you can use this function. 


See also TMDIChild 


GetCommandTarget 

virtual HWND GetCommandTarget(); 

Locates and returns the child window that is the target of the command and command 
enable messages. If the current application does not have focus or if the focus is within a 
toolbar in the application, GetCommandTarget returns the most recently active child 
window. 


If an alternative form of command processing is desired, a user's main window class can 
override this function. TFrameWindow's EvCommand and EvCommandEnable functions 
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TFrameWindow class 


use GetCommand Target to find the command target window. This member is not 
available under Presentation Manager. | 


GetMenuDescr_ | -_ 
const TMenuDescr* GetMenuDescr(); 
Returns a pointer to the menu descriptor. 


See also aneiaramibes lemma TMenuDescr 


HoldFocusHWnd 

bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain); 

Overrides TWindow’s virtual function. Responds to a request by a child window to hold 
_ its HWND when it is losing focus. Stores the child's HWND in HwndRestoreFocus. 


See also TWindow::HoldFocusHiwnd 


IdleAction 

void IdleAction(long idleCount); | 

Overrides TWindow’s virtual function. TApplication calls the main window's IdleAction 
when no messages are waiting to be processed. TFrameWindow uses this idle time to 
perform command enabling for the menu bar. It also forwards IdleAction to each of its 
children. IdleAction can be overridden to do background processing. 


Seealso TApplication::IdleAction 


MergeMenu 

bool MergeMenu(const TMenuDescr& childMenuDescr): | 
Merges the given menu descriptor with this frame's own menu descriptor and displays 
the resulting menu in this frame. See TMenuDescr co a description of menu bar types 
that can be merged. 


See also TMenuDescr 


PreProcessMsg 

bool PreProcessMsg(MSG& msg); 

Overrides TWindow’s virtual function. Performs preprocessing of window messages. If 
the child window has requested keyboard navigation, PreProcessMsg handles any: 
accelerator key messages and then processes any other keyboard messages. 


See also TWindow::PreProcessMsg 


RestoreMenu 
bool RestoreMenu(); 3 
Restores the default menu of the frame window. 


SetClientWindow 

virtual TWindow* SetClientWindow(TWindow* clientWnd); 

Sets the client window to the specified window. Users are responsible for destroying the 
old client window if they want to eliminate it. 


SetDocTitle 
bool SetDocTitle(const char far* docname, int index); 
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TFrameWindow class 


Overrides TWindow’s virtual function. Pastes the number of the view into the caption 
and then shows the number on the screen. This function can be overridden if you don't 
want to use the default implementation, which displays a number on the screen.. That is, 
you might want to write "Two" instead of "2" on the screen. For an example of the 
behavior of this function, see step 12 of the ObjectWindows tutorial, which renumbers- 
the views if one of them is closed. 


Seticon 

bool Setlcon(TModule* iconModule, TResld iconResld); 

Sets the icon in the module specified in iconModule to the resource ID specified in 
iconResld. See the sample file bmpview.cpp for an example of painting an icon from a 


bitmap. You can set the iconResId to one of these pre-defined values as well as user- 
defined values: 


IDILLAPPLICATION _ Default icon used for applications 


IDI_ASTERISK Asterisk used for an informative message 
IDILEXCLAMATION _ Exclamation mark used for a warning message 
IDI_HAND Hand used for warning messages 
IDI_QUESTION Question mark used for prompting a response 


Seealso TFrameWindow::EvQueryDraglcon 


SetiMenu 

virtualBOOL SetMenu(HMENU newMenu); 

Overrides TWindow’s non-virtual SetMenu function, thus allowing derived classes the 
opportunity to implement this function differently from TWindow. SetMenu sets the 
window's menu to the menu indicated by newMenu. If newMenu is 0, the window's 
current menu is removed. SetMenu returns 0 if the menu remains unchanged; otherwise, 
it returns a nonzero value. 


SetMenuDescr 
void SetMenuDescr(const TMenuDescr& menuDescr); 
Sets the menu descriptor to the new menu descriptor. 


See also TFrameWindow::GetMenuDescr, TMenuDescr 


Protected data members 


ClientWnd 
TWindow* ClientWnd; 
ClientWnd points to the frame's client window. 


DocTitlelndex 
int DocTitlelndex; 
Holds the index number for the document title. 


HWndRestoreFocus 
HWND HWndRestoreFocus; 
Stores the handle of the child window whose focus gets restored. 
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TFrameWindow class 


- Seealso TFrameWindow: ‘HoldFocusHwnd | 


MergeModule 

TModule* MergeModule; — 

Tells the frame window which module the menu comes from. TDecoratedFrame uses this 
member to get the menu hints it displays at the bottom of the screen. It assumes that the 
menu hints come from the same place the menu came from. 


Protected constructor 


Constructor 

TFrameWindow(); 

Protected constructor used in conjunction with Init function for initializing virtually 
derived classes. 


Protected member functions 


EvCommand 

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode); 

Provides extra processing for commands and lets the focus anon and its parent 
windows handle the command first. 


EvCommandEnable 
void EvCommandEnable(TCommandEnabler& ce); 
Handles checking and unchecking of the frame window's menu items. 


EvEraseBkgnd 

bool EvEraseBkgnd(HDC); 

EvEraseBkgnd erases the background of the window specified in HDC. It returns true if 
the background is erased; otherwise, it returns false. 


EvinitMenuPopup 

HANDLE EvinitMenuPopup(HMENU hPopupMenu, uint index, bool sysMenu); 

Sent before a pop-up menu is displayed, EvInitMenuPopup lets an application change 
the items on the menu before the menu is displayed. EvInitMenuPopup controls whether 
the items on the pop-up menu are enabled or disabled, checked or unchecked, or 
strings. HMENU indicates the menu handle. index is the index of the pop-up menu. 
sysMenu indicates if the pop-up menu is the system menu. 


EvPaint 

void EvPaint(); | 

Responds toa WM_PAINT message in the client window in order to paint the iconic 
window's icon or to allow client windows a change to paint the icon. 


Seealso TWindow::Paint, ace al TScroller::End View 


EvParentNotify 
void EvParentNotify(uint event, uint childHandleOrx, uint leas 
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TFrameWindow class 


Responds to a message to notify the parent window that a given event has occurred. If 
the client window is destroyed, closes the parent window. If shrinkToClient is set and the 
child window has changed size, the frame is adjusted. 


When a TFrameWindow’s client window is destroyed, the TFrameWindow object sees the 
WM_PARENTNOTIFY message and posts a close message to itself. Without this 
message, an empty frame would remain and the client window would then have to 
determine how to destroy the frame. If you don't want this to happen, you can derive 
from the frame window and have your application handle the EvParentNotify or EvClose 
messages. | 


EvQueryDraglcon 

HANDLE EvQueryDraglcon(); 

Responds to a WM_QUERYDRAGICON message sent to a minimized (iconic) window 
that is going to be dragged. Instead of the default icon, EvQueryDraglcon uses the icon 
that was set using SetIcon. 


This member is not available under Presentation Manager. 


See also —TFrameWindow::SetIcon 


EvSetFocus 

void EvSetFocus(HWND hWndLostFocus); 

Restores the focus to the active window. hWndLostFocus contains the handle for the 
window that lost focus. 


EvSize 

void EvSize(uint sizeType, TSize& size); 

Resizes the client window's size so that it is equivalent to the client rectangle's size. Calls 
TWindow::EvSize) in response to an incoming WM_SIZE message. 


Seealso TSize 


Init | 

void Init (TWindow* clientWnd, bool shrinkToClient); 

This initialize function is for use with virtually derived classes, which must call Init 
before construction is completed. This procedure provides necessary data to virtually 
derived classes and takes care of providing the data in the appropriate sequence. 


SetupWindow 

void SetupWindow(); 

Calls TWindow::SetUpWindow to create windows in a child list. SetupWindow performs 
the initial adjustment of the client window if one exists, assigns the frame's menu based 
on the menu descriptor, and initializes HwndRestoreFocus. 


Seealso TWindow::SetUpWindow 
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TGadget class 


Response table entries 


git 


EV_WM_INITMENUPOPUP EvInitMenuPopup 
EV_WM_PAINT EvPaint 
EV_WM_PARENTNOTIFY EvParentNotify 
EV_WM_QUERYDRAGICON EvQueryDraglcon (Windows only) 
EV_WM_SETFOCUS EvSetFocus | 
EV_WM SIZE | | EvSize ° 
TGadget class gadget.h 


TGadget is the base class for the following derived gadget classes: 


TButtonGadget Uses a bitmap to similate a button gadget. 

TControlGadget Encapsulates inserting a control such as an edit control or a combobox, into a gadget 
window. 7 | 

TTextGadget Displays text. 


TSeparatorGadget Separates logical groups of gadgets. 


TGadget interface objects belong to a gadget window, have borders and margins, and 
have their own coordinate system. The margins are the same as those for 
TGadgetWindow and borders are always measured in border units. 


To set the attributes for the gadget, you can either choose a border style (which 
automatically sets the individual border edges) or set the borders and then override the 
member function PaintBorder to create a custom look for your gadget. If you change the 
borders, margins, or border style, the gadget window's GadgetChangedSize member 
function is invoked. 


Although, by default, gadgets shrink-wrap to fit around their contents, you can control 
this attribute by setting your own values for ShrinkWrapWidth and ShrinkWrapHeight. 


A gadget window, being an actual window, receives messages from the mouse. After 
the gadget window receives the message, it decides which gadget should receive the 
message by calling the member function directly instead of sending or posting a 
message. | 


See also 
TBitmapGadeget, TButtonGadget, TControlGadget, TTextGadget, TSeparatorGadget 
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TGadget class 


Public constructors and destructor 


Constructor — 
TGadget(int id = 0, TBorderStyle = None); 
Constructs a TGadget object with the specified ID and border style. 


Destructor 
virtual ~TGadget(); 
Destroys a TGadget interface object and removes it from its associated window. 


Public data members 


Clip 

bool Clip; 

If Clip is false, clipping borders have not been established. If Clip is true, the drawing for 
each gadget is restrained by the gadget's border. 


WideAsPossible 

bool WideAsPossible; 

Initially set to false, WideAsPossible indicates whether the gadget width will be adjusted 
by the gadget window to be as wide as possible in the remaining space. 


Seealso TGadgetWindow::WideAsPossible 


Public enums and structs 


TBorders 
struct TBorders { 
unsigned Left; 
unsigned Right; 
unsigned Top; 
unsigned Bottom; 
TBorders(){Left=Right=Top=Bottom=0;} 
}; 
TBorders structure holds the values for the left, right, top, and bottom measurements of 
the gadget. 


TBorderStyle 

enum TBorderStyle {None, Plain, Raised, Recessed, Embossed}; 

Enumerates an exclusive list of border styles: none, plain, raised (the gadget appears to 
be raised above the gadget window), recessed (the gadget appears to be recessed into 
the gadget window), or embossed (the gadget appears to have an embossed border). For 
an example of border styles, see the sample ObjectWindows program, MDIFILE.CPP, 
on your distribution disk. 


TMargins 

struct TMargins { 
enum TUnits {Pixels, LayoutUnits, BorderUnits}; 
TUnits Units; | 
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int Left; 

int Right; 

int Top; 

int Bottom; 
TMargin(){Units=LayoutUnits;Left=Right=Top=Bottom=0;} 


Used by the TGadgetWindow and TGadget classes, TMargins contains the measurements 
of the margins for the gadget. The constructor initializes Units to nen and sets 
Left, Right, Top, and Bottom equal to 0. | 


See also TGadgetWindow::SetMargins 


Public member functions 


CommandEnable 

virtual void CommandEnable(); 

CommandEnable is provided so that the gadget can perform command enabling (so it can 
handle an incoming message, if it's epee uae to do so). 


GetBorders 

TBorders& GetBorders(); 

Gets the gadget's borders measured in border units that are based on SM_CXBORDER 
and SM_CYBORDER. 


Seealso TGadget::SetBorders 


GetBorderStyle 
TBorderStyle GetBorderStyle(); 
Gets the style for the gadget's borders. 


See also TGadget::SetBorderStyle 


GetBounds 
TRect& GetBounds(); 
Returns the boundary rectangle for the gadget. 


Seealso TButtonGadget::SetNotchCorners 


GetDesiredSize 

virtual void GetDesiredSize(TSize& size); 

GetDesiredSize determines how big the gadget can be. The gadget window sends this 
message to query the gadget's size. If shrink-wrapping is requested, GetDesiredSize 
returns the size needed to accommodate the borders and margins. If shrink-wrapping is 
not requested, it returns the gadget's current width and height. TGadget Window needs 
this information to determine how big the gadget needs to be, but it can adjust these 
dimensions if necessary. If WideAsPossible is true, then the width parameter (size.cx) is 
ignored. 


GetEnabled 
bool GetEnabled(); . 
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Determines whether keyboard and mouse input have been enabled for the specified 
gadget. If the gadget is enabled, GetEnabled returns true; otherwise, it returns false. By 
default, keyboard and mouse input are enabled. 


Seealso TGadget::SetEnabled 


Getld 
int Getld(): 
Gets the ID for the gadget. 


GetMargins 
TMargins& GetMargins(); 
Gets the margin dimensions. 


GetOuterSizes 
void GetOuterSizes(int& left, int& right, int& top, int& bottom); 
Returns the amount of space (in pixels) taken up by the borders and margins. 


NextGadget 
TGadget* NextGadget(); 
Returns the next gadget in the list of gadgets. 


SetBorders 

void SetBorders(TBorders& borders); 

Sets the borders for the gadget. If the borders are changed, SetBorders calls 
TGadgetWindow::GadgetChangedSize to notify the gadget window of the change. 


See also TGadget::GetBorders, TGadgetWindow::GadgetChangedSize 


SetBorderStyle 
void SetBorderStyle(TBorderStyle); 
Sets the border style for the gadget. 


Seealso TGadget::GetBorderStyle 


SetBounds 

virtual void SetBounds(TRect& rect); 

SetBounds informs the gadget of a change in its bounding rectangle. Although the 
default behavior updates only the instance variable Bounds, you can override this 
method to also update the internal state of the gadget. 


SetEnabled 

virtual void SetEnabled(bool); 

Enables or disables keyboard and mouse input for the gadget. By default, the gadget is 
disabled when it is created and must be enabled before it can be activated. 


See also TGadget::GetEnabled 


SetMargins 

void SetMargins(TMargins& margins); 

Sets the margins of the gadget. If the margins are changed, SetMargins calls 
TGadgetWindow::GadgetChangedSize to notify the gadget window. 


Seealso TGadget::;GetMargins 
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SetShrinkWrap 

void SetShrinkWrap(bool shrink Wrap Wiath, bool shrinkWrapHeight): 

Sets the ShrinkWrapWidth and ShrinkWrapHeight data MeebeS. Your derived class can 
call TGadgetWindow's GadgetChangedSize member function if you want to change the 
size of the gadget. 


See also TGadgetWindow: eadeelChenecdo7e 


SetSize 
void SetSize(TSize& size); 

SetSize alters the size of the gadget and then calls TGadgetWindow: :GadgetChangedSize for 
the size change to take effect. 


This function is needed only if you have turned off shrink-wrapping in one or both 
dimensions; otherwise, use the GetDesiredSize member function to return the shrink- 
wrapped size. 


SysColorChange 

virtual void SysColorChange(); 

SysColorChange is called when the system colors have been changed s so that gadgets can 
rebuild and repaint, if necessary. —— 


Protected data members 


Bounds 
TRect Bounds; 
Contains the bounding rectangle for the gadget in n gadget window coordinates. 


Seealso TGadget::GetInnerRect 


Borders 
TBorders Borders; 
Contains the border measurements s fT Gadget::GetInnerRect 


BorderStyle 
TBorderStyle BorderStyle; 
Contains the border style for the gadget. 


Id 

int Id; 

Contains the gadget's ID. 

Margins — 

TMargins Margins; | 
Contains the margin measurements of the rectangle or the gadget. 


Seealso TGadget::GetInnerRect 


ShrinkWrapHeight 
bool ShrinkWrapHeight; | 
Indicates if the gadget is to be shrink-wrapped to fit around its contents. 
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ShrinkWrapWidth 
bool ShrinkWrapWidth; 
Indicates if the gadget is to be shrink-wrapped to fit around its contents. 


TrackMouse 

bool TrackMouse; 

Initialized to false. When TrackMouse is true, the gadget captures and releases the mouse 
on LButtonDown and LButtonUp by calling TGadget Window's GadgetSetCapture and 
Gadget ReleaseCapture. 


Seealso TGadget::LButtonDown, TGadget: ngs 


Window 
TGadgetWindow* Window; 
References the owning or parent window fei the gadget. 


Protected member functions 


GetinnerRect 
void GetInnerRect(TRect& rect); 
Computes the area of the gadget's rectangle excluding the borders and margins. 


Inserted 
virtual void Inserted(); 
Called after a gadget is inserted into a window. 


Invalidate 

void Invalidate(bool erase = true); 

Used to invalidate the active (usually nonborder) portion of the gadget, Invalidate calls 
InvalidateRect and passes the boundary width and height of the area to erase. 


InvalidateRect 
void InvalidateRect(const TRect& rect, bool erase = true); 
Invalidates the gadget-relative rectangle in the parent window. 


LButtonDown 

virtual void LButtonDown(uint modKeys, TPoint& point); 

Captures the mouse if TrackMouse is set. point is located in the gadget's coordinate 
system. 


Seealso TGadget::TrackMouse 
LButtonUp 
virtual void LButtonUp(uint modKeys, TPoint& point); 


Releases the mouse capture if TrackMouse is set. point is located in the gadget's 
coordinate system. 


Seealso TGadget::TrackMouse 


MouseEnter 
virtual void MouseEnter(uint modKeys, TPoint& point); 
Called when the mouse enters the gadget. 
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See also TGadget::MouseLeave 


MouseLeave 
virtual void MouseLeave(uint modKeys, TPoint& point); 
Called when the mouse leaves the gadget. 


Seealso TGadget::MouseEnter 


_ MouseMove 
virtual void MouseMove(uint modKeys, TPoint& point); 
If mouse events are captured, EvMouseMove responds to a mouse aiseeine message. » 
point is located in the receiver's coordinate system. 


See also TGadget::MouseEnter, TGadget::MouseLeave — 


Paint 
virtual void Paint(TDC&): 
Calls PaintBorder to paint the indicated device context. 


Seealso TTextGadget::Paint 


PaintBorder 

virtual void PaintBorder(TDC& dec); 

Used to paint the border, PaintBorder calls ::GetSystemMetrics to obtain the width and 
height of the gadget and uses the color returned by GetSyscolor to paint or highlight the — 
area with the specified brush. Depending on whether the border style is raised, 
embossed, or recessed, PaintBorder paints the specified boundary. You can override this 
function if you want to implement a border style that isn't supported y 
ObjectWindows' s gadgets. 


Ptin 

virtual bool Ptin(TPoint& point); 

PtIn determines if the point is within the receiver's bounding rectangle and returns true 
if this is the case; otherwise, returns false. 


_ Removed 
virtual void Removed(); 
Called after a gadget is removed from a window. 


Update 
void Update(); 
Repaints the gadget if possible. 


Derived from TFont, TGadgetWindowFont is a specific font used in gadget windows for 
sizing and default text. You can specify the point size of the font (not the size in pixels) 
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and whether it is bold or italic. You can use one of the following FF_xxxx constants to 
indicate the font family type: 


FF DECORATIVE 


FF_DONTCARE The font type does not matter. 
FF_ MODERN Fonts such as Pica, Elite or Courier with a constant stroke, width, and with or 
without serifs. 
- FF_LROMAN Fonts such as Times New Roman and New Century Schoolbook with varied 
stroke and with serifs. 
FF_SCRIPT Fonts such as Script that are designed to resemble handwriting. 
FF_SWISS Fonts such as MS Sans Serif with variable stroke width and without serifs. 


Depending on the typeface, the font weight can be one of the following constants: 


‘The font weight does not matter. 
FW_THIN Thin 

FW_EXTRALIGHT Extra light 

FW_ULTRALIGHT Extra light 


FW_LIGHT Light 
FW_NORMAL Normal 
FW_REGULAR Normal font weight 
FW_MEDIUM Medium 
FW_SEMIBOLD Somewhat bold 
FW_DEMIBOLD Somewhat bold 
FW_BOLD Bold 
FW_EXTRBOLD Extra bold 
FW_ULTRBOLD Extra bold 
FW_BLACK Heavy weight 
FW_HEAVY Heavy weight 


The font's appearance depends on the typeface so that some fonts only have 
FW_NORMAL, FW_REGULAR and FW_BOLD available. If FW_DONTCARE is 
indicated, the default font weight is used. 


Public constructor 


Constructor | 

TGadgetWindowFont(int pointSize = 10, bool bold = false, bool italic = false); 

Constructs a TGadgetWindowFont interface object with a default point size of 10 picas 
without bold or italic typeface. By default, the constructor creates the system font: a 
variable-width, sans-serif Helvetica. 


Seealso Jiont 
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Derived from TWindow, TGadgetWindow maintains a list of tiled praises ee a window 
and lets you dynamically arrange tool bars. You can specify the following attributes of 
these gadgets: | 


Horizontal or vertical tiling. Positions the cadgets horizontally or vertically within 
the inner rectangle (the area excluding borders and margins). 7 


Gadget font. Default font to use for gadgets and for calculating layout units. For font 
information, see the description of TGadgetWindowFont. 


Left, right, top, and bottom margins. Specified in pixels, layout units (based on the 
window font), or border units (the width or height of a thin window border). 


Measurement units. Specified in pixels, layout units, or border units. 


Gadget window size. A gadget window can shrink-wrap its width, height, or both to 
fit around its gadgets. By default, horizontally tiled gadgets shrink-wrap to fit the 
height of the window and vertically tiled gadgets shrink-wrap to fit the width of the 
window. 


TGadgetWindow is the base class for the following derived classes: T'ControlBar, 
i ai TToolBox, and eee 


Public constructor and destructor 


Constructor | 
TGadgetWindow(TWindow* parent = 0, TTileDirection direction = Horizontal, 


TFont *font = new TGadgetWindowFont, TModule* module = 0); 


Creates a TGadgetWindow interface object with the default tile direction and font fd 
passes module with a default value of 0. 


Destructor 
~TGadgetWindow(); 
Destructs the TGadgetWindow object by deleting all of its gadgets and fonts. 


Type definitions 


THintMode 

enum THintMode{NoHints, PressHints, EnterHints}; | 
Enumerates the hint mode settings of the gadget—either no hints, hints whena buttonis _ 
pressed, or hints when the mouse passes over a gadget. . 


Seealso TGadgetWindow::GetHintMode 


Public member functions 


FirstGadget | 
TGadget* FirstGadget() const; 
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Returns the FirstGadget in the list. 
Seealso TGadgetWindow::FirstGadget 


GadgetChangedSize 

void GadgetChangedSize(TGadget& gadget); 

Used to notify the gadget window that a gadget has changed its size, GadgetChangedSize 
calls LayoutSession to re-layout all gadgets. 


Seealso TGadget::SetShrinkWrap, TGadgetWindow::GadgetChangedSize 


GadgetFromPoint 
TGadget* GadgetFromPoint(TPoint& point); 
Returns the gadget at the given window coordinates. 


GadgetReleaseCapture 
void GadgetReleaseCapture(TGadget& gadget); 
Releases the capture so that other windows can receive mouse messages. 


Seealso TGadgetWindow::GadgetSetCapture 


GadgetSetCapture 

bool GadgetSetCapture(TGadget& gadget); 

GadgetSetCapture reserves all mouse messages for the gadget window until the capture 
is released. Although gadgets are always notified if a left button-down event occurs 
within the rectangle, the derived gadget class must call GadgetSetCapture if you want the 
gadget to be notified when a mouse drag and a mouse button-up event occurs. 


Seealso TGadgetWindow::GadgetReleaseCapture 


GadgetWithid 
TGadget* GadgetWithld(int id) const; 
Returns a pointer to the gadget associated with the given ID (id). 


GetDirection | 
TTileDirection GetDirection() const; 
Gets the horizontal or vertical orientation of the gadgets. 


Seealso TGadgetWindow::SetDirection 
GetFont 


TFont& GetFont(); 
Returns the font (which is Sans Serif by default). 


Seealso TGadgetWindowFont::TGadgetWindowFont 
GetFontHeight 


uint GetFontHeight() const; 
Gets the height of the window's font. 


GetHintMode 
THintMode GetHintMode(); 
Returns the hint mode. 
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IdleAction 

void IdleAction(); 

While no messages are waiting to be processed, IdleAction is called and iterates through 
the gadgets, invoking their CommandEnable member function. 


Seealso TGadget::CommandEnable 


Insert 

virtual void Insert(TGadget& gadget, TPlacement = After, TGadget *sibling = 0); 

Inserts a gadget before or after a sibling gadget (TPlacement). If sibling is 0, then the new 
gadget is inserted at either the beginning or the end of the gadget list. If this window has 
already been created, LayoutSession needs to be called after inserting gadgets. 


Seealso TGadgetWindow::LayoutSession, TGadgetWindow::Remove 


LayoutSession 

virtual void LayoutSession(); 3 
LayoutSession is typically called when a change occurs in the size of the margins or _ 
gadgets or when gadgets are added or deleted. LayoutSession calls TileGadgets to tile the 
gadgets in the specified direction and Invalidate to mark the area as invalid (needs 
repainting). 


Seealso TGadgetWindow::Insert, TCadgetWindow: ‘Remove, TWindow::Invalidate 


NextGadget 
TGadget* NextGadget(TGadget& gadget) const; 
Returns the next gadget after gadget or 0 if none exists. 


Remove 

virtual TGadget* Remove(TGadget& gadget); 

Removes a gadget from the gadget window. The gadget is returned but not deswoved 
Remove returns 0 if the gadget is not in the window. 


If this window has already been created, the calling application must call LayoutSession 
after any gadgets have been removed. 


Seealso TGadgetWindow::Insert, TGadgetWindow::LayoutSession 


SetDirection 

virtual void SetDirection(TTileDirection direction); 

Sets the horizontal or vertical orientation of the gadgets. If the gadget window is already 
created, SetDirection readjusts the dimensions of the gadget window to fit around the 
gadgets. 


The setting of the direction parameter is also related to the setting of the second . 
parameter (Tlocation) in TDecoratedFrame’s Insert function,. which specifies where the 
decoration is added in relation to the frame window's client window. If the second 
parameter in TDecoratedFrame::Insert is set to top or bottom, the direction parameter in 
SetDirection must be horizontal. If the second parameter in TDecoratedFrame::Insert is set 
to left or right, the direction parameter in SetDirection must be vertical. 


Seealso TGadgetWindow::GetDirection 
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SetHintCommand 

void SetHintCommand(int id); 

Simulates menu selection messages so that ObjectWindows command processing can 
display command hints for the given command id (CM_xxxx). 


Seealso CM xxxx edit constants, CM_xxxx edit file constants 


SetHintMode 

void SetHintMode(THintMode hintMode); 

Sets the mode of the hint text. Defaults to PressHints (displays hint text when a button is 
pressed). 


Seealso —THintMode enum 


SetMargins 
void SetMargins(TMargins& margins); 
Sets or changes the margins for the gadget window and calls LayoutSession. 


See also TGadgetWindow::Margins 


SetShrinkWrap 

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight); 

Sets the width and height of the data members. By default, if the tile direction is | 
horizontal, ShrinkWrapWidth is false and ShrinkWrapHeight is true. Also by default, if the 
direction is vertical, ShrinkWrapWidth is true and ShrinkWrapHeight is false. 


Protected data members 


AtMouse 
TGadget* AtMouse; 
The last gadget at the mouse position. 


BkgndBrush 
TBrush* BkgndBrush; 
The color of the background brush. 


Capture 

TGadget* Capture; 

Points to the gadget that currently has the mouse capture; otherwise, if no gadget has 
the mouse capture, Capture is 0. 


Seealso TGadgetWindow::GadgetSetCapture 


Direction 
TTileDirection GetDirection() const; | 
Gets the horizontal or vertical orientation of the gadgets. 


Seealso TGadgetWindow::SetDirection 


DirtyLayout 
bool! DirtyLayout; 
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Indicates the layout has shanged and gadgets need to be re-tiled. Using DirtyLayout 
avoids redundant tiling when gadget windows are created. 


See also TGadgetWindow::LayoutSession 


Font 
TFont* Font; 
Points to the font used to calculate layout units. 


Seealso TGadgetWindow::GetFont 


FontHeight 
uint GetFontHeight() const; 
Gets the height of the window's font. 


Gadgets 
TGadget* Gadgets; ' 
Points to the first gadget in the gadget list. 


HintMode 
THintMode HintMode; 
Holds the hint text mode. 


Seealso THintMode enum 


Margins 
TMargins Margins; 
Holds the margin values for the gadget window. 


Seealso TGadgetWindow::SetMargins 


NumGadgets 
uint NumGadgets; 
The number of gadgets in the window. 


ShrinkWrapHeight 

bool ShrinkWrapHeight; 

If ShrinkWrapHeight is true, the window will shrink its width to fit the tallest gadget for 
horizontally tiled gadgets. 


Seealso TGadgetWindow::SetShrinkWrap 


ShrinkWrapWidth 

bool ShrinkWrapWidth; 

If ShrinkWrapWidth is true, the window will shrink its width to fit the widest gadget for 
vertically tiled gadgets. 


Seealso TGadgetWindow::SetShrinkWrap 


_ WideAsPossible 
uint WideAsPossible; 
The number of gadgets that are as wide as possible. 
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Protected member functions 


Create 

bool Create(); 

Overrides TWindow member function and chooses the initial size of the gadget if shrink- 
wrapping was requested. 


Seealso TGadgetWindow::SetShrinkWrap 


EvLButtonDown 

void EvLButtonDown(uint modKeys, TPoint& point); 

Responds to a left button-down mouse message by forwarding the event to the gadget 
positioned under the mouse. 


EvLButtonUp 

void EvLButtonUp(uint modKeys, TPoint& point); 

Responds to a left button-up mouse message by forwarding the event to the gadget that 
has the capture. 


EvMouseMove 

void EvMouseMove(uint modKeys, TPoint& point); 

If mouse events are captured, EvMouseMove responds to a mouse move message by 
forwarding the event to the gadget that has the capture. 


EvSize 

void EvSize(uint sizeType, TSize& size); 

Calls TWindow::EvSize to perform any default processing. If DirtyLayout true and 
WideAsPossible is greater than 0, EvSize sets DirtyLayout to true and calls TileGadgets to 
readjust the size and Invalidate to mark the area for redrawing. 


EvSysColorChange 

void EvSysColorChange(); 

EvSysColorChange, which is called when any system colors have changed, forwards the 
event to all gadgets. 


GetDesiredSize 

virtual void GetDesiredSize(TSize& size); 

If shrink-wrapping was requested, GetDesiredSize returns the size needed to 
accommodate the borders and the margins of the widest and highest gadget; otherwise, 
it returns the width and height in the window's Attr structure. 


If you want to leave extra room for a specific look (for example, a separator line between 
gadgets, a raised line, and so on), you can override this function. However, if you 
override GetDesiredSize, you will probably also need to override GetInnerRect to 
calculate your custom inner rectangle. 


Seealso TGadgetWindow::GetInnerRect 


GetinnerRect 
virtual void GetInnerRect(TRect& rect); 
GetInnerRect computes the rectangle inside of the borders and margins of the gadget. 
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If you want to leave extra room for a specific look (for example, a separator line between 

gadgets, a raised line, and so on), you can override this function. If you override 
GetInnerRect, you will probably se need to override GetDesiredSize to calculate your 
custom total size. 


Seealso TGadgetWindow::GetDesiredSize 


GetMargins 
void GetMargins(TMargins& margins, int& lett, int& right, int& top, int& bottom); 
Returns the left, right, top, and bottom margins in pixels. 


_LayoutUnitsToPixels 
int LayoutUnits ToPixels(int units); 
Converts layout units to pixels. A layout unit is determined by dividing the window 
font height by eight. 


Seealso TGadgetWindow::LayoutSession 


Paint 
void Paint(TDC& dc, bool erase, TRect& rect); 
Puts the font into the device context and calls PaintGadgets. 


Seealso TGadgetWindow::PaintGadgets 


PaintGadgets 

virtual void PaintGadgets(TDC& dc, bool erase, TRect& rect); 

Called by Paint to repaint all of the gadgets, PaintGadgets iterates through the list of 
gadgets, determines the gadget's area, and repaints each gadget. 


You can override this function to implement a specific look (for example, separator line, 
raised, and so on). 


PositionGadget 

virtual void PositionGadget(TGadget* previous, TGadget* next, TPoint& pcint); 

PositionGadget is called to allow spacing adjustments to be made before each gadget is 
positioned. 


See also TGadgetWindow::TileGadgets 


TileGadgets 
virtual void TileGadgets(); 
Tiles the gadgets in the direction requested (horizontal or vertical). 


Calls PositionGadget to give derived classes an opportunity to adjust the spacing 
between gadgets i in their windows. _ 


See also TGadgetWindow::PositionGadget 
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Response table entries 


Res ae _ Member function. . 
EV_WM.LBUITTONDOWN __—EwLButtonDown 
EV_WM_LBUTTONUP EvLButtonUp 
EV_WM_MOUSEMOVE EvMouseMove 

EV_WM. SIZE EvSize 


EV_WM_SYSCOLORCHANGE — EvSysColorChange 


TGaugeclass gs 


A streamable class derived from TControl, TGauge defines the basic behavior of gauge 
controls. Gauges are display-only horizontal or vertical controls that provide duration 
or analog information about a particular process. A typical use of a gauge occurs in 
installation programs where a control provides a graphical display indicating the 
percentage of files copied. In general, horizontal gauges with a broken (dashed-line) bar 
are used to display short-duration, process information whereas horizontal gauges with 
a solid bar are used to illustrate long-duration, process information. Usually, vertical 
gauges are preferred for displaying analog information. 


Public constructor 


Constructor 
TGauge(TWindow* parent, const char far’ title, int id, int X, int Y, int W, int H, bool isHorizontal = true, 

int margin = 0, TModule* module = 0); 
Constructs a TGauge object with borders that are determined by using the value of 
SM_CXBORDER. Sets IsHorizontal to isHorizontal. Sets border thickness and spacing 
between dashed borders (LEDs) to 0. Sets the range of possible values from 0 to 100. 


Public member functions 


GetRange 
void GetRange(int& min, int& max) const; 
Gets the minimum and maximum values for the gauge. 


GetValue 
int GetValue() const; 
Gets the current value of the gauge. 


SetColor 
void SetColor(TColor color); 
Sets the BarColor data member to the value specie’ in color. 


SetLed 
void SetLed(int spacing, int thick = 90); 
Sets the LedSpacing and LedThick data members to the values spacing and thick. 
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—SetRange 
void SetRange(int min, int max); 
Sets the Min and Max data members to min and max values returned by the constructor. 
If Max is less than or equa! to Min, SetRange resets Max to Min plus 1. 


SetValue 

void SetValue(int value); 

Restricts the value so that it is within the minimum and 1 maximum values established 
for the gauge. If the current value has changed, SetValue marks the old position for 
repainting. Then, it sets the data member Value to the new value. 


Protected data members 


BarColor 
TColor BarColor; 
Holds the bar or LED color, which defaults to blue. 


IsHorizontal 

int IsHorizontal; 

Set to the ishorizontal argument of the constructor. IsHorizontal i is true if the gauge is 
horizontal and false if it is vertical. 


LedSpacing 

int LedSpacing; 

Holds the integer value (in gauge units) of the spacing between the broken bars of the 
gauge. Note that TGauge does not paint the title while using LED spacing. 


LedThick 

int LedThick; 

Holds the thickness of the broken bar. 

Margin 

int Margin; 

Contains the border width and height of the gauge. 


Max 

int Max; 

Holds the maximum value (in gauge units) displayed on the gauge. 
Min 

int Min; 

Holds the minimum value (in gauge units) displayed on the gauge. 


Value 
int Value; 
Holds the current value of the gauge. 
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Protected member functions 


EvEraseBkgnd 

bool EvEraseBkgnd(HDC); 

Overrides TWindow’'s EvEraseBkgnd function and erases the background of the gauge. 
Whenever the background is repainted, EvEraseBkgnd is called to avoid flickering. 


Paint 

void Paint(TDC& dc, bool erase, TRect& rect); 

Overrides TWindow’s Paint function and paints the area and border of the gauge. Paints 
the given rectangle on the given device context. Uses the values in LedSpacing and 
IsHorizontal to paint draw a horizontal or vertical gauge with solid or broken bars. 


Seealso TGauge::LedSpacing, TGauge::IsHorizontal, TDC, TRect 


PaintBorder 

virtual void PaintBorder(TDC& dc); | 

Paints the gauge border using the specified device context. Depending on whether the 
border style is raised, embossed, or recessed, PaintBorder paints the specified boundary. 
You can override this function if you want to implement a border style that isn't 
supported by ObjectWindows' gauges. 


Response table entries 


EV_WM_ERASEBKGND _ EvEraseBkgnd 


GdiObject is the root, pseudo-abstract base class for ObjectWindows' GDI (Graphics 
Device Interface) wrappers. The TGdiOject-based classes let you work with a GDI 
handle and construct a C++ object with an aliased handle. Some GDI objects are also 
based on TGdiObject for handle management. Generally, the TGdiObject-based class 
hierarchy handles all GDI lee apart from the DC (Device Context) objects handled 
by the TDC-based tree. 


The five DC selectable classes (TPen, TBrush, TFont, TPalette, and TBitmap), and the 
TIcon, TCursor, TDib, and TRegion classes, are all derived directly from TGdiObject. 


TGdiObject maintains the GDI handle and a ShouldDelete flag that determines if and 
when the handle and object should be destroyed. Protected constructors are provided 
for use by the derived classes: one for borrowed handles, and one for normal use. 


An optional orphan control mechanism is provided. By default, orphan control is active, 
but you can turn it off by defining the NO_GDI_ORPHAN_CONTROL identifier: 


#define NO_GDI_ORPHAN_ CONTROL 


With orphan control active, the following static member functions are available: 
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RefAdd, RefCount, RefDec, RefFind, RefInc, aad RefRemove. 


These maintain object reference counts and allow safe orphan recovery and deletion. 
Macros, such as OBJ_REF_ADD, let you deactivate or activate your orphan control code 
by simply defining or undefining NO_GDI_ORPHAN_CONTROL. When 
NO_GDIORPHAN_CONTROL is undefined, for example, OBJ_REF_ADD(handle, 
type) expands to TGdiObject::RefAdd((handle),(type)), but when 
NO_GDI_LORPHAN_CONTROL is defined, the macro expands to handle. 


Public destructor 


Destructor 

~TGdiObject(): 

It ShouldDelete is false no action is taken. Otherwise with ShouldDelete true, the action of 
the destructor depends on whether orphan control is active or not. If orphan control is 
inactive (that is, if NOLORPHAN_CONTROL is defined) ~TGdiObject deletes the GDI 
object. If orphan control is active (the default) the object is deleted only if the reference 
count is 0. 


Type definitions 


TAutoDelete © 

enum TAutoDelete{NoAutoDelete, AutoDelete}; 

This enum, which is defined in the private base class, edibase. h, enumerates the flag 
values for GDI Handle constructors. This flag is used to control GDI object deletion in 
the destructors. 


_ TType 
enum TType {None, Pen, Brush, Font, Palette, Bitmap, TextBrush}; 
This enumeration is used to store the object type in the struct TObjInfo. This internal 
structure is used to track object reference counts during debugging sessions. 


Seealso TGdiObject::RefCount 


Public member functions 


GetObject 

int GetObject(int count, void far* object) const; 

Obtains information about this GDI object and places it in the object buffer. If the call 
succeeds and object is not 0, GetObject returns the number of bytes copied to the object 
buffer. If the call succeeds and object is 0, GetObject returns the number of bytes needed 
in the object buffer for the type of object being queried. Depending on what type of GDI 
object is derived, this function retrieves a LOGPEN, LOGBRUSH, LOGFONT, or 
BITMAP structure through object. 


Seealso TPen::GetObject, BITMAP struct, LOGBRUSH struct, LOGFONT struct, 
LOGPEN struct 
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RefAdd 

static void RefAdd(HANDLE handle, TType type); 

Available only if orphan control is active (that is, if NO_GDILORPHAN_CONTROL is 
undefined). RefAdd adds a reference entry for the object with the given handle and type to 
the ObjInfoBag table and sets the reference count to 1. If the table already has a matching 
entry, no action is taken. 


Seealso TGdiObject::RefCount, macro OBJ_REF_ADD 


RefCount 

static int RefCount(HANDLE handle); 

Available only if orphan control is active, that is, if NO_GDI_ORPHAN_CONTROL is 
undefined. RefCount returns this object's current reference count or —1 if the object is not 
in the ObjInfoBag table. 


See also macro OBJ REF COUNT 


RefDec 

static void RefDec(HANDLE handle); 

static void RefDec(HANDLE handle, bool wantDelete); 

Available only if orphan control is active, that is, if NO_GDI_ORPHAN_CONTROL is 
undefined. RefDec decrements this object's reference count by 1 and deletes the object 
when the reference count reaches zero. A warning is issued if the deletion was supposed 
to happen but didn't. Likewise, a warning is issued if the deletion wasn't supposed to 
happen but did. The deleted object is also detached from the ObjInfoBag table. 


The second version of RefDec is available only if the __TRACE identifier is defined. You 
can vary the normal deletion strategy by setting wantDelete to true or false. 


See also TGdiObject::RefCount, macro OBJ_REF_DEC 


RefFind 

static TObjinfo* RefFind(HANDLE object); 

Available only if orphan control is active (that is, if NO_GDI_ORPHAN the given object 
is undefined). If found, the object's type and reference count are returned in the 
specified TObjInfo object. RefFind returns 0 if no match is found. 


Seealso TGdiObject::RefCount 


Refine 

static void Reflnc(HANDLE handle); 

Available only if orphan control is active (that is, if NO_GDI_LORPHAN_CONTROL is 
undefined). Reflnc increments by 1 the reference count of the object associated with 
handle. 


Seealso TGdiObject::RefCount, macro OBJ_REF_INC 

RefRemove 

static void RefRemove(HANDLE handle); 

Available only if orphan control is active (that is, if NO_GDI_LORPHAN_CONTROL is 


undefined). RefRemove removes the reference entry to the object with the given handle 
from the ObjInfoBag table. If the given handle is not found, no action is taken. 


Seealso TGdiObject::RefCount, macro OBJ_REF_REMOVE 
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Form 1 


Form 2 


— Operator HGDIOBJ) 


operator HGDIOBJ() const | 
Type casting epee that converts this GDI object handle to OES HGDIOB]J. 


Protected data members 
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Handle 
HANDLE Handle; 
The GDI handle of this object. 


See also TGdiObject protected constructors 


ShouldDelete 
bool ShouldDelete; 
Set true if the Destructor needs to delete this object's GDI handle. 


See also TGdiObject Protected Constructors 


Protected member functions 


CheckValid 
void CheckValid( uint resid=IDS_GDIFAILURE) 
static void CheckValid( HANDLE handle, uint resid=IDS _GDIFAILURE) 


Both versions of CheckValid check for a valid GDI object handle. If one is not found a 
GDI ed aA is thrown for the given resource id. 


Protected constructors 


Constructors 

TGdiObject(); 

This default constructor sets Handle to 0 and ShouldDelete to true. This constructor is 
intended for use by derived classes that must set the Handle member. 


TGdiObject(HANDLE handle, TAutoDelete autoDelete = NoAutoDelete); | 

This constructor is intended for use by derived classes only. The Handle data member is 
"borrowed" from an existing handle given by the argument handle The ShouldDelete data 

member defaults to false ensuring that the borrowed handle will not be deleted when _ 

the object is destroyed. 


See also TGdiObject: -enumT AutoDelete, TCdiObject: ‘Handle, TGdiObject::RefCount, 
TGdiObject::ShouldDelete 


Macros 


OBJ_REF_ADD 

OBJ _REF_ADD(handle, type) 

If orphan control is active (the default), OBJ_REF_ADDvhandle, type) is defined as 
TGdiObject::RefAdd((handle), (type)). The latter adds to the ObjInfoBag table a reference 
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entry for the object with the given handle and type, and sets its count to 1. If orphan 
control is inactive, OBJ_REF_ADDv(handle) is defined as handle. This macro lets you write 
orphan control code that can be easily deactivated with the single statement #define 
NO_GDI_LORPHAN_CONTROL. 


See also TGdiObject::RefAdd 


OBJ_REF_COUNT 

OBJ_ ‘REF COUNT (handle) 

If orphan control is active (the default), OB J_REF_COUNT* (handle) is defined as 
TGdiObject::RefCount((handle)). The latter returns the reference count of the object with 
the given handle, or —1 if no such object exists. If orphan control is inactive, 
OBJ]_REF_COUNT (handle) is defined as —1. This macro lets you write orphan control 
code that can be easily deactivated with the single statement #define 
NO_GDI_ORPHAN_CONTROL. 


See also TGdiObject::RefCount 


OBJ_REF_DEC 

OBJ REF DEC(handle, wantDelete) 

If orphan control is active (the default), OBJ_REF_DEC (handle, wantDelete) is defined as 
either TGdiObject::RefDec((handle)) or TGdiObject::RefDec((handle), (wantDelete)). The 
latter format occurs only if __TRACE is defined. RefDec(handle) decrements the 
reference count of the object associated with handle and optionally deletes orphans or 
warns you of their existence. If orphan control is inactive, OBJ_REF_DEC(handle) is 
defined as handle. This macro lets you write orphan control code that can be easily 
deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL. 


Seealso TGdiObject::RefDec 


OBJ_REF_INC 

OBJ_REF_INC(handle) 

If orphan control is active (the default), OBJ_REF_INC(handle) is defined as 
TGdiObject::RefInc((handle)). The latter increments the reference count of the object 
associated with handle. If orphan control is inactive, OBJ_REF_DEC(handle) is defined as 
handle. This macro lets you write orphan control code that can be easily deactivated with 
the single statement #define NO_GDI_ORPHAN. CONTROL. 


Seealso TGdiObject::RefInc 


OBJ_REF_REMOVE 

OBJ _REF_REMOVE(handle) 

If orphan control is active (the default), OBJ_REF_REMOVE(handle) is defined as 
TGdiObject::RefRemove((handle)). The latter removes from the ObjInfoBag table the 
reference entry for the object associated with handle. It orphan control is inactive, 
OBJ_REF_REMOVE (handle) is defined as handle. This macro lets you write orphan 
control code that can be easily deactivated with the single statement #define 
NO_GDI_ORPHAN_CONTROL. 


Seealso TGdiObject::RefRemove 
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Describes an exception resulting from GDI failures such as creating too many TWindow 
DCs. This exception occurs, for example, if a DC driver can't be located or if a DIB file 
can't be read. 


The following oiled from the PAINT.CPP sample program on your distribution disk © 
throws a TXGdi exception if a new DIB can't be created. 


void TCanvas::NewDib(int width, int height, int nColors} 
TDib* dib; 
bry | 
dib = new TDib(width, height, nColors); 
} 
catch (TGdiObject::TXGdi& x) { 
MessageBox("Could Not Create DIB", GetApplication()->Name, 
MB_OK); 
return; 


} 


Public constructor 


Constructor 
TXGdi(uint resid = IDS_GDIFAILURE, HANDLE = 0); 
Constructs a TXGdi object with a default IDS_GDIFAILURE message. 


Public member functions | 


Clone 

TXOwl* Clone(); | 

Makes a copy of the exception object. Clone must be implemented in any class derived 
from TXOuwl. 


Msg 
Static string Msg(uint resid, HANDLE): | 
Converts the resource ID to a string and returns the string message. 


Throw 
void Throw(); 
Throws the exception object. Throw must be implemented i in any class devived from 
— TXOwil. 
TGroupBox class oe groupbox.h 


An instance of a TGroupBox is an interface object that represents a corresponding group 
box element. Generally, TGroupBox objects are not used in dialog boxes or dialog 
windows (TDialog), but are used when you want to create a group box in a window. 


250 ObjectWindows Reference Guide 


Form 1 


Form 2 
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Although group boxes don't serve an active purpose onscreen, they visually unify a 
group of selection boxes such as check boxes and radio buttons or other controls. Behind 
the scenes, however, they can take an important role in handling state changes for their 
group of controls (normally check boxes or radio buttons). 


For example, you might want to respond to a selection change in any one of a group of 
radio buttons in a similar manner. You can do this by deriving a class from TGroupBox 
that redefines the member function SelectionChanged. 


Alternatively, you could respond to selection changes in the group of radio buttons by 
defining a response for the group box's parent. To do so, define a child-[D-based 
response member function using the ID of the group box. The group box will 
automatically send a child-ID-based message to its parent whenever the radio button 
selection state changes. This class is streamable. 


Public data members 


NotifyParent 

bool NotifyParent; 

Flag that indicates whether parent is to be notified when the state of the group box's 
selection boxes has changed. NotifyParent is true by default. 


Public constructors 


Public constructors 

TGroupBox(TWindow* parent, int Id, const char far *text, int x, int y, int w, int h, TModule* module = 0); 
Constructs a group box object with the supplied parent window (Parent), control ID (Id), 
associated text (text), position (x, y) relative to the origin of the parent window's client 
area, width (w), and height (h). Invokes the TControl constructor with similar 
parameters, then modifies Attr.Style, adding BS_GROUPBOX and removing 
WS_TABSTOP. NotifyParent is set to true; by default, the group box's parent is notified 
when a selection change occurs in any of the group box's controls. 


TGroupBox(TWindow* parent int resourceld, TModule* module = 0); 

Constructs a TGroupBox object to be associated with a group box control of a TDialog. 
Invokes the TControl constructor with identical parameters resourceID must correspond 
to a group box resource that you define. 


Seealso TControl::TControl, TWindow::DisableTransfer 


Public member functions 


GetClassName 

char far* GetClassName(); 

GetClassName returns the name of TGroupBox’s Windows registration class, "BUTTON." 
If BWCC is enabled, GetClassName returns BUTTON_CLASS. 


SelectionChanged 
virtual void SelectionChanged(int controlld); 
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If NotifyParent’ is true, Seetonc hanged notifies the parent window of the group box that 
one of its selections has changed by sending it a child-ID-based message. This member 
function can be redefined to allow the group box to handle selection changes in its 
group of controls. 


_ Derived from TBrush, THatch8x8Brush defines a small, 8x8, monochrome, configurable 
hatch brush (a brush that fills an area with a pattern created from hatch marks). Because 
the hatch brush is a logical brush created from device independent bitmaps (DIBs), it 
can be passed to any DC, which then renders the brush into the a a form for the 
particular device. 


Although the default brush's color is a white foreground and a black Backeround you 
can vary the colors of the hatched brush. The colors can be any one of the TColor object 
encapsulated colors, namely the standard RGB values. 


_THatch8x8Brush contains static arrays that define common hatched brush patterns. The 
hatched brush patterns you can select include 


Forward Diagonal / / / / Ve 
| fd LEAL TE TH. 
Backward Diagonal \ \ \ \ \ \ 
A. WL A AX 


You can use THatch8x8Brush to design a variety of hatched brush border patterns 
around a simple rectangle or an OLE container. You can also use THatch8x8Brush in 
conjunction with TU[Handle. 


Public data members 


Hatch11F1[8] 

const static uint8 Hatch11F 1[8]; | 

The static array, Hatch11F1 [8] holds the logical hatched brush pattern of 1 pixel on and 
1pixel off in monochrome, offset 1 per row as the following pattern illustrates. 


Hatch13B1 8) 

const static uint8 Hatch13B1[8]; 

The static array, Hatch13B1[8] holds a hatched brush pattern of 1 pixel on and 3 pixels off 
_in backward diagonal hatch marks, offset 1 per row as the following pattern illustrates. 


SSRSSSIKSSS 


Hatch13F1[8] 
const static uint8 Hatch13F1[8]; 
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The static array, Hatch13F1[8] holds a hatched brush pattern of 1 pixel on and 3 pixels off 
in forward diagonal hatch marks, offset 1 per row as the following pattern illustrates. 


Hatch22B1[8] 

const static uint8 Hatch22B 1{8}: 

The static array, Hatch22B1[ 8] holds a ee brush pattern of 2 pixels on and 2 off in 
backward diagonal hatch marks, offset 1 per row as the following pattern illustrates. 


= TS 


Hatch22F1[8] 

const static uint8 Hatch22F 1[8}; 

The static array, Hatch22F1[8] holds a hatched brush pattern of 2 pixels on and 2 off in 
forward diagonal hatch marks, offset 1 per row as the following pattern illustrates. 


LES 


Public constructors 


Constructor 

THatch8x8Brush(const uint8 hatch], TColor fgColor=TColor::White, TColor bgColor=TColor::Black); 
Constructs a THatchBrush object with the specified hatched pattern and colors. 
Although the hatched brush is, by default, white on a black background, you can control 
the displayed colors by passing different colors in the constructor where fgColor 
represents the foreground color and bgColor represents the background color of a TColor 
object type. Colors can be specified in either palette (a reference to a corresponding color 
palette entry in the currently realized palette) or RGB mode (an actual red, green, or blue 
color value). 


Public member functions 
Reconstruct 


void Reconstruct(const uint8 hatch{], TColor fgColor, TColor bgColor); 
Reconstructs the hatched brush with a new pattern or new set of colors. 


Seealso Brush, TColor, TUIHandle 


TIC class de.h 


Derived from TDC, TIC is a DC class that provides a constructor for creating a DC object 
from explicit driver, device, and port names. 
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Public enamine 


Constructor 


TIC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData=0): 
Creates a DC object with the given driver, device, and port names and initialization 
values. 


Seealso T’DC::GetDeviceCaps, DEVMODE struct 


Ticon class ete gdiobjec.h 


Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


Form 6 


Form 7 


TIcon, derived from TGdiObject, represents the GDI object icon class. TIcon constructors 
can create icons from a resource or from explicit information. Because icons are not real 
GDI objects, the TIcon destructor overloads the base destructor, ~TGdiObject. 


Public constructors and destructor 


Constructors 

Ticon(HICON handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TIcon object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 


Ticon(HINSTANCE instance, const Tlcon& icon); 
Creates a copy of the given icon object. 


Ticon(HINSTANCE instance, TResID resID); 
Creates an icon object from the given resource. 


Tilcon(HINSTANCE instance, const char far* filename, int index); 
Creates an icon object from the given resource file. 


Ticon(HINSTANCE instance, const TSize& size, int planes, int bitsPixel, const void far* andBits, 


const void far* xorBits); 
Creates an icon object with the given values. 


TIcon(const void* resBits, uint32 resSize); | 
Creates an icon object of the given size from the bits found in the resBits buffer. 


TIcon(const ICONINFO* iconInfo); 
Creates an icon object with the given ICONINFO information. 


Destructor 
~TIcon(); 
Destroys the icon and frees any memory that the icon occupied. 


Seealso 9 ~TGdiObject, TGdiObject::Handle, TGdiObject::ShouldDelete,, TResID, TSize, 
ICONINEFO structure 
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Public member functions 


Geticoninfo 

bool GeticonInfo(ICONINFO* iconInfo) const; 

Retrieves information about this icon and copies it into the given ICONINFO structure. 
Returns true if the call is successful; otherwise returns false. 


Seealso ICONINFO structure 


operator HICON() 

operator HICON() const; 

Typecasting operator that converts this icon's Handle to type HICON (the data type 
representing the handle to an icon resource). 


TInputDialog provides a generic dialog box to retrieve text input by a user. When the 
input dialog box is constructed, its title, prompt, and default input text are specified. 
TInputDialog is a streamable class. 


Public data members 


buffer 

char far* buffer; 

Pointer to the buffer that returns the text retrieved from the user. When passed to the 
constructor of the input dialog box, contains the default text to be initially displayed in 
the edit control. 


BufferSize 
int BufferSize; 
Contains the size of the buffer that returns user input. 


prompt 
char far* prompt; 
Points to the prompt for the input dialog box. 


Public constructor 


Constructor 

TInputDialog(TWindow* parent, const char far “title, const char far *prompt, char far* butter, int buffersize, 
TModule* module = 0, TValidator* valid = 0) | 

Invokes TDialog’s constructor, passing it parent, the resource identifier and module. Sets 

the caption of the dialog box to title and the prompt static control to prompt. Sets the 

Buffer and BufferSize data members to buffer and bufferSize. 


Seealso TDialog::TDialog 
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Public member function - 


TransferData 

void TransferData(T TransferDirection direction); 

Transfers the data of the input dialog box. If direction is tdSetData, sets the text of the 
static and edit controls of the dialog box to the text in prompt and buffer. If direction is 
Sees fills the buffer with the current text of the Editor. | 


Protected member function 

SetupWindow 

virtual void SetupWindow(); 

In setting up the window, SetupWindow calls TDialog:: SetupWindow, then limits the 
number of characters the user can enter to bufferSize -1. , 


TinStream class a _ docview.h 
Derived from TStream and istream, TInStream is a base class used for defining input 
streams for documents. 


Public constructor 


Constructor 

TinStream(TDocument& doc, const char far* name, int mode); 

Constructs a TInStream object. doc refers to the document object, name is the user-defined 
name of the stream, and mode is the mode of opening the stream. 


Seealso TOutStream, ofXXXX document open enum, shxxxx document sharing enum 


TLayoutConstraint struct _ layoutco.h 


TLayoutConstraint is a structure that defines a relationship (a layout constraint) between 

an edge or size of one window and an edge or size of one of the window's siblings or its 

parent. If a parent-child relationship is established between windows, the dimensions of 

the child windows are dependent on the parent window. A window can have one of its 

sizes depend on the size of the opposite dimension. For example, the width can be twice 

the height. TLayoutMetrics lists the relationships you can have among size and edge 
constraints. 
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The sample file LAYOUT.CPP shows you the following example of how to set up layout 
constraints. 


Layout child windows 


: Layout Window 
Layout 
Layout Child 


Relayout Children e 


Set these metrics to control 
the position and size of the 
layout child window. 


Public data members 


MyEdge 

uint MyEdge; 

MyEdge contains the name of the edge or size constraint (ImTop, lmBottom, lmLeft, 
lmRight, ImCenter, lmWidth, or ImHeight) for your window. 


See also TWidthHeight enum 


OtherEdge 

uint OtherEdge; | 

OtherEdge contains the name of the edge or size constraint (ImTop, ImBottom, lmLeft, 
ImRight, lmCenter, lmWidth, or lmHeight) for the other window. 


Seealso TWidthHeight enum 


Relationship 

TRelationship Relationship; | 

Relationship specifies the type of relationship that exists between the two windows (that 
is, lmRightOf, lmLeftOf, ImAbove, ImBelow, lmSameAs, or lmPercentOf). A value of 
ImAbsolute actually indicates that no relationship exists. 


Seealso TRelationship enum 


RelWin 
TWindow *RelWin; 
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RelWin is a pointer to the sibling windows or ImParent if the child is a proportion of the 
parent's dimensions. Rel!Win points to the window itself (this) if a child window's 
dimension is a proportion of one of its other dimensions (for example, its height is a 
proportion of its width). | 


See also TRelationship enum — 


Units 
TMeasurementUnits Units; 
Units enumerates the units of measurement (either pixels or layout units) used to 
_ measure the height and width of the windows. Unlike pixels, layout units are based on 
_ system font size and will be consistent in their perceived size even if the screen 
resolution changes. | 


Seealso JMeasurementUnits enum 


union 
union { 

int Margin; 

int Value; 

int Percent; 
} 
This union is included for the convenience of naming the layout constraints. Margin is 
used for the ImAbove, ImLeftOf, ImLeftOf, or lmRightOf enumerated values in 
TRelationship. Value is used for the ImSameAs or ImAbsolute enumerated values in — 
TRelationship. Percent is used for the lmPercentOf enumerated value in TRelationship. 


Seealso TMeasurementUnits enum 


TLayoutMetrics contains the four layout constraints used to define the layout metrics for 
a window. This table lists the constraints you can use for the X, Y, Height, and Width 
fields. 


Xx ImLeft, ImCenter, ImRight 

Y ImTop, lmCenter, ImBottom 
Height ImCenter, ImRight, lmWidth 
Width ImCenter, ImBottom, ImHeight | 


If the metrics for the child window are relative to the parent window, the relation 
window pointer (/mParent) needs to be lmParent (not the actual parent window pointer). 
For example, , 


TWindow* child = new TWindow(this, ""); 

TLayoutMetrics metrics; 7 

metrics.X.Set(lmCenter, lmSameAs, lm()t, IlmCenter) ; 

metrics.Y.Set(IlmCenter, ImSameAs, lm()t, ImCenter) ; 
_ SetChildbayoutMetrics(*child, metrics) ; 
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The parent window pointer (this) should not be used as the relation window pointer of 
the child window. 


Public data members 


Height 

TEdgeOrWidthConstraint Height; 

Contains the height size constraint, center edge, or bottom edge constraint of the 
window. 


Width 

TEdgeOrWidthConstraint Width; 

Contains the width size constraint, center edge, or right edge (ImRight) constraint of the 
window. 


X,Y 

TEdgeConstraint X, Y; 

X contains the X (left, center, right) edge constraint of the window. Y contains the Y (top, 
center, bottom) edge constraint of the window. 


Public constructor 


Constructor 

TLayoutMetrics(); 

Creates a TLayoutMetrics object and initializes the object by setting the units for the child 
and parent window to the specified layout units and the relationship between the two 
windows to what is defined in ImAsIs (of TRelationship). Sets the following default 
values: 


-RelWin = 0; 

.MyEdge = ImLeft; 
.Relationship = ImAsIs; 
Units = ImLayoutUnits; 
.Value = 0; 

.RelWin = 0; 

MyEdge = ImTop; 
.Relationship = IlmAsIs; 
Units = lmLayoutUnits; 
.Value = 0; 

Width.RelWin = 0; 
Width.MyEdge = lmWidth; 
Width.Relationship = lmAsIs; 
Width.Units = lmLayoutUnits; 
Width.Value = 0; 

Height .RelWin = 0; 

Height .MyEdge = lmHeight; 
Height.Relationship = lmAsIs; 
Height .Units = lmLayoutUnits; 
Height.Value = 0; 


KeMRC KK RX XX RX DX 
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The following program creates two child windows and a frame into which you can add 
layout constraints. 


#include <owl\owl.h> 
#include <owl\framewin.h> 
#include <owl\applicat.h> 

- #include <owl\layoutwi.h> 

- #include <owl\decorate.h> 
#include <owl\decmdifr.h> 
#include <owl\layoutco.h> 
#pragma hdrstop 


// Create a derived class. // 


class TMyDecoratedFrame : public TDecoratedFrame { 
public: 
TMyDecorat edFrame (TWindow* parent, const char far* title, TWindows& clientWnd, TWindow* MyC 
hildwWindow) ; 
void SetupWindow(); 
{ 
TDecoratedFrame: :SetupWindow(); 
MyChi1ldWindow->ShowWindow (SW_NORMAL) ; 
MyChildwWindow->BringWindowToTop (); 
} 
ti 


// Setup a frame window // 


TMyDecoratedFrame: :TMyDecoratedFrame(TWindow * parent, const char far * 
title, TWindow& clientWnd) 
: TDecoratedFrame (parent, title, clientWnd), 
TFrameWindow(parent, title, &clientWnd) , 
TWindow(parent, title). 
{ 
// Create a new TMyChildWindow. // 


MyChildWindow = new TWindow(this, ""); 
MyChildWindow->Attr.Style |= WS_BORDER |WS_VISIBLE |WS_CHILD; 
MyChildwindow->SetBkgndColor (RGB(0,100,0)); 


// Establish metrics for the child window. // 
TLayoutMetrics layoutMetrics; 


layoutMetrics.X.Absolute(lmLeft, 10); 

layoutMetrics.Y.Absolute(lmTop, 10); 

layoutMetrics.Width.Absolute( 80 }; 

layoutMetrics.Height .Absolute( 80 ); 
} | 
SetChildLayoutMetrics (*MyChildWindow, layoutMetrics) ; 
class TMyApp : public TApplication { 
public: | 
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virtual void InitMainWindow( } 
{ 
TWindow* client = new TWindow(0, "title"); 
MainWindow = new TMyDecoratedFrame(0, "Layout Window Ex", *client); 
} 
ie 
int OwlMain(int, char**) { 
return TMyApp.Run(); 
} 


Derived from TWindow, TLayoutWindow provides functionality for defining the layout 
metrics for a window. By using layout constraints, you can create windows whose 
position and size are proportional to another window's dimensions. In other words, the 
one window constrains the size of the other window. Toolbars and status bars are 
examples of constrained windows. See TLayoutConstraint for a definition of the layout 
constraints and TLayoutMetrics for a description of the metrics you can use to set up 
layout constraints. 


The following examples show how to set up various metrics using edge constraints. For 
purposes of illustration, these examples use a parent-child relationship, but you can also 
use a child-to-child (sibling) relationship. Keep in mind that, as usual, if you move the 
parent's origin (the left and top edges), the child will move with the parent window. 


Examples 


Example 1 

To create growable windows, set the top and left edges of the child window's 
boundaries in a fixed relationship to the top and. left edges of the parent's window. In 
this example, if you expand the bottom and right edges of the parent, the child's bottom 
and right edges grow the same amount. Both the X and Y constraints are 10 units from 
the parent window's edges. Both the Width and Height constraints are 40 layout units 
from the parent window's edges. Specifically, Width (ImWidth) is 40 units to the left of 
the parent's right edge (ImLeftOf = ImSameAs + offset or sameas — 40). 


40 Width 


40 Height 


Use the following layout constraints: 
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layoutmetrics.X.Set(lmLeft, ImRightOf, lm()t, Imbeft, 10); 
layoutmetrics.Y.Set(lmTop, ImBelow, Im()t, ImTop, 10); 

-layoutmetrics.Width.Set(lmRight, lmLeftOf, lmParent, ImRight, 40); 
layoutmetrics.Height.Set(lmBottom, ImAbove, ImParent, ImBottom, 40); 
SetChildLayoutMetrics(*MyChildWindow, layoutMetrics) ; 

Example 2 | : 

To create fixed-size and fixed-position windows, set the child's right edge a fixed 
distance from parent's left edge and the child's bottom edge a fixed distance from the 
parent's top edge. In this example, both the X and Y edge constraints are set to 10 and 
both the Width and Height edge constraints are set to 100. 


Height = 100 


—-—__» 
Width = 100 


Use the following layout constraints: 


layoutmetrics.X.Set(lmLeft, lmRightOf, lmParent, ImLeft, 10); 
layoutmetrics.Y.Set(lmTop, lmBelow, lmParent, ImTop, 10); 
layoutmetrics.Width. Absolute (100); 

layoutmetrics.Height .Absolute(100); 

SetChildLayoutMetrics (*MyChildWindow, layoutMetrics) ; 


Example 3 

To create a fixed-size window that remains a constant distance from the parent's right 
corner, set the child's top and bottom edges a fixed distance (JmLayout unit or pixels) 
from the parent window's bottom. Also, set the child's left and right edges a fixed 
distance from the parent's right edge. In this example, both the Width and the Height 
edge constraints are set to 10 and the X and Y edge constraints are set to 100. In this case, 
the child window, which stays the same size, moves with the lower right corner of the 
parent. 


Width = 100 
<->» 


Height = 100 


Use the following layout constraints: 


layoutmetrics.X.Set(lmRight, lmLeftOf, lmParent, lmRight, 10); 
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layoutmetrics.Y.Set (ImBottom, lImAbove, lmParent, ImBottom, 10); 
layoutmetrics.Width.Absolute(100); 
layoutmetrics.Height .Absolute (100) ; 
SetChildLayoutMetrics(*MyChildWindow, layoutMetrics) ; 


Example 4 

To create a window in which the child's edges are a percentage of the parent's window, 
set the child's edges a percentage of the distance from the parent's edges. Specifically, 
the child's top and bottom edges are a percentage of the parent's bottom edge. The 
child's left and right edges are a percentage of the parent's right edge. 


If you resize the parent window, the child window will change size and origin (that is, 
the top and left edges will also change). 


Width = 66% 


Height = 66% 


Use the following layout constraints: 


layoutmetrics.X.Set(lmLeft, lmPercentOf, lmParent, lmRight, 33); 
layoutmetrics.Y.Set(lmTop, lmPercentOf, lmParent, lmBottom, 33); 
layoutmetrics.Width.Set(lmRight, ImPercentOf, lm()t, lmRight, 66); 
layoutmetrics.Height.Set(lmBottom, lmPercentOf, Im()t, ImBottom, 66); 
SetChildLayoutMetrics(*MyChildWindow, layoutMetrics) ; 


Public constructor and destructor 


Constructor 
TLayoutWindow(TWindow* parent, const char far *title = 0, TModule* module = 0); 
_ Creates a TLayoutWindow object with specified parent, window caption, and library ID. 


Destructor 
~TLayoutWindow(); 
Deletes variables and frees the child metrics and constraints. 


Public member functions 


GetChildLayoutMetrics 
bool GetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics); 
Gets the layout metrics of the child window. 


Layout 
void Layout(); 
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Causes the window to resize and position its children according to the specified metrics. 
Call Layout to implement changes that occur in the layout metrics. 


" RemoveChildLayoutMetrics 
bool RemoveChildLayoutMetrics(TWindow &child); 
Removes the layout metrics for a child window. 


SetChildLayoutMetrics | 
void SetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics); 

Sets the metrics for the yaneow and removes any existing ones. Set the metrics as 
shown: 


i 


layoutMetrics->X.Absolute(lmLeft, 10); 

layoutMetrics->Y.Absolute(lmTop, 10); 

layoutMetrics->Width.Set (1mWidth, ImRightOf, GetClientWindow(), lmWidth, -40); 
layoutMetrics->Height.Set (lmHeight, ImRightOf, GetClientWindow(), ImHeight, -40); 


Then call SetChildLayoutMetrics to associate them with the position of the child window: 


SetChildLayoutMetrics(* MyChildWindow, * layoutMetrics); 


Protected data member 
ClientSize 


TSize ClientSize; 
Contains the size of the client area. 


Protected member functions 
EvSize 


void EvSize(uint sizeType, TSize& size); 
Responds to a change in window size by calling Layout to resize the window. 


Response table entries 


EV_WM_SIZE EvSize 


TListBox class © - a listbox.h 


A TListBox is an interface object that represents a corresponding list box element. A 
TListBox must be used to create a list box control in a parent TWindow. A TListBox canbe | 
used to facilitate communication between your application and the list box controls of a 
TDialog. TListBox's member functions also serve instances of its derived class, 
TComboBox. From within MDI child windows, you can access a TListBox object by using 
TFrameWindow::GetClientWindow. TListBox is a streamable class. 
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Public constructors 


Constructors 

TListBox(TWindow* parent, int Id, int x, int y, int w, int h, TModule* module = 0); 

Constructs a list box object with the supplied parent window (parent) library ID 
(module), position (x, y) relative to the origin of the parent window's client area, width 
(w), and height (h). Invokes a TControl constructor. Adds LBS_STANDARD to the 
default styles for the list box to provide it with 


e A border (WS_BORDER) 

e A vertical scroll bar (WS_VSCROLL) 

e Automatic alphabetic sorting of list items (LBS_SORT) 

e Parent window notification upon selection (LBS_NOTIFY) 


The TListBox member functions that are described as being for single-selection list boxes 
are inherited by TComboBox and can also be used by combo boxes. Also, these member 
functions return —1 for multiple-selection list boxes. 


TListBox(TWindow* parent, int resourceld, TModule* module = 0) 

Constructs a TListBox object to be associated with a list box control of a TDialog. Invokes 
the TControl constructor with similar parameters. The module parameter must 
correspond to a list box resource that you define. 


Seealso GetSelIndex, GetSelString, SetSelIndex, SetSelString, TControl::TControl 


Public member functions 


AddString 

virtual int AddString(const char far* str); 

Adds string to the list box, returning its position in the list (0 is the first position). 
Returns a negative value if an error occurs. The list items are automatically sorted unless 
the style LBS_SORT is not used for list box creation. 


Seealso T'ListBox::DeleteString, TListBox::InsertString 


ClearList 
virtual void ClearList(); 
Clears all items in the list. 


DeleteString 

virtual int DeleteString(int index); 

Deletes the item in the list at the position (starting at 0) supplied in index. DeleteString 
returns the number of remaining list items, or a negative value if an error occurs. 


Seealso TListBox::AddString, TListBox::InsertString 


DirectoryList 
virtual int DirectoryList(uint attrs, const char far* fileSpec) 
Adds a list of file names to a list box. 
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: FindExactString 
int FindExactString(const char far* str, int sdarchbiden const: 
Starting at the line number passed in searchIndex, searches the list box fei an exact match | 
_ with the string str. If a match is not found after the last string has been compared, the 
search continues from the beginning of the list until a match has been found or until the 
list has been completely traversed. Searches from the beginning of the list when-lis 
supplied as searchIndex. Returns the index of the first string found if successful, a 
negative value if an error occurs. 


See also TListBox::AddString, TListBox::DeleteString | 


FindString 

virtual int FindString(const char far* str, int Index) const; 

Searches the list box as described under FindExactString, but gous for the first entry that 
begins with str. 


Seealso TListBox::AddString, TListBox::DeleteString, TListBox::InsertString 


GetCaretindex 

int GetCaretIndex() const; 

Returns the index of the currently focused list-box item. For single-selection list boxes, 
the return value is the index of the selected item, if one is selected. 


Seealso ‘TListBox::SetCaretIndex 


GetCount 
virtual int GetCount() const; | 
Returns the number of items in the list box, or a negative value if an error occurs. 


GetHorizontalExtent 
int GetHorizontalExtent() const; 
Returns the number of pixels by which the list box can be scrolled horizontally. 


Seealso TListBox::SetHorizontalExtent 
GetitemData 


virtual uint32 GetltemData(int index) const; 
_ Returns the 32-bit value of the list box item set by SetItemData. 


See also TListBox::SetItemData 
GetitemHeight | 


virtual int GetltemHeight(int index) const; 
Returns the height in pixels of the specified list box items. 


Seealso TListBox::SetItemHeight 
GetitemRect | 
int GetltemRect(int index, TRect& rect) const; 


Returns the dimensions of the rectangle that surrounds a list-box i item currently 
displayed in the list-box window. 


GetSel 
bool GetSel(int index) const; 
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Returns the selection state of the list-box item at location index. Returns true if the list- 
box item is selected, false if not selected. 


Seealso TListBox::SetSel 


GetSelCount 

int GetSelCount() const; 

Returns the number of selected items in the single- or multiple-selection list box or 
combo box. 


GetSelindex 

virtual int GetSellndex() const; 

For single-selection list boxes. Returns the nonnegative index (starting at 0) of the 
currently selected item, or a negative value if no item is selected. 


Seealso TListBox::SetSellndex 


GetSelindexes 

int GetSellndexes(int* indexes, int maxCount) const; 

For multiple-selection list boxes. Fills the indexes array with the indexes of up to 
maxCount selected strings. Returns the number of items put in indexes (—1 for single- 
selection list boxes and combo boxes). 


Seealso TListBox::SetSelIndexes 


GetSelString 

int GetSelString(char far* str, int maxChars) const; 

Retrieves the currently selected items, putting up to maxChars of them in Strings. Each 
entry in the Strings array should have space for maxChars characters and a terminating 
null. For single-selection list boxes, returns the string length, a negative value if an error 
occurs, or 1 if no string is selected. For multiple-selection list boxes, returns —1. 


Seealso TListBox::SetSelString 


GetSelStrings 

int GetSelStrings(char far** strs, int maxCount, int maxChars) const; 

Retrieves the total number of selected items for a multiselection list and copies them into 
the buffer. str is an array of pointers to chars. Each of the pointers to the buffers is of 
maxChars. maxCount is the size of the array. 


Seealso TListBox::SetSelStrings 


GetString 

virtual int GetString(char far* str, int index) const; 

Retrieves the item at the position (starting at 0) supplied in index and returns it in str. 
GetString returns the string length, or a negative value if an error occurs. 


GetStringLen 

virtual int GetStringLen(int Index) const; 

Returns the string length (excluding the terminating NULL) of the item at the position 
index supplied in Index. Returns a negative value in the case of an error. 
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GetTopindex 
int GetTopIndex() const: 
Returns the index of the first item displayed at the top of the list box. 


Seealso TListBox::SetTopIndex 


InsertString 

virtual int InsertString(const char far* str, int index); 

Inserts str in the list box at the position supplied in index, and returns the item's actual 
position (starting at 0) in the list. A negative value is returned if an error occurs. The list 
is not resorted. If index is —1, the string is appended to the end of the list. 


Seealso TListBox::AddString, TListBox::DeleteString, TListBox::FindString 


SetCaretindex | 

int SetCaretIndex(int index, bool partScrollOk); 

Sets the focus to the item specified at index. An item that is not visible is scrolled into 
view. 


Seealso TListBox::GetCaretIndex 


SetColumnWidth | 
void SetColumnWidth(int width); 
Sets the width in pixels of the items in the list box. 


SetHorizontalExtent 
void SetHorizontalExtent(int horzExtent); 
Sets the number of pixels by which the list box can be scrolled horizontally. 


Seealso TListBox::GetHorizontalExtent 


SetitemData 
virtual int SetltemData(int index, uint32 itemData); 
Sets the 32-bit value of the list box item at the specified index position. 


Seealso TListBox::GetItemData 


SetitemHeight 
virtual int SetltemHeight(int index, int height); 
Sets the height in pixels of the items in the list box. 


See also TListBox::GetItemHeight | 


SetitemRect 

int SetitemRect(int index, TRect& rect) const; 

Sets the dimensions of the rectangle that surrounds a list-box item currently diviaved 
in the list-box window. | 


SetSel | 
int SetSel(int index, bool select); 
Selects an item at the position specified in index. For multiple-selection list boxes. 


Seealso TListBox::GetSel 
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SetSellndex ~ 

virtual int SetSellndex(int index); 

For single-selection list boxes. Forces the selection of the item at the position (starting at 
0) supplied in index. If index is -1, the list box is cleared of any selection. SetSelIndex 
returns a negative number if an error occurs. 


SetSellndexes 

int SetSellndexes(int* indexes, int numSelections, bool shouldSet); 

For multiple-selection list boxes. Selects /deselects the strings in the associated list box at 
the indexes specified in the Indexes array. If ShouldSet is true, the indexed strings are 
selected and highlighted; if ShouldSet is false the highlight is removed and they are no 
longer selected. Returns the number of strings successfully selected or deselected (—1 for 
single-selection list boxes and combo boxes). If NumSelections is less than 0, all strings 
are selected or deselected, and a negative value is returned on failure. 


SetSelitemRange 
int SetSelltemRange(bool select, int first, int last); 
Selects the range of items specified from first to last. 


SetSelString 

int SetSelString(const char far* str, int searchIndex); 

For single-selection list boxes. Forces the selection of the first item beginning with the 
text supplied in str that appears beyond the position (starting at 0) supplied in 
SearchIndex. If SearchIndex is -1, the entire list is searched, beginning with the first item. 
SetSelString returns the position of the newly selected item, or a negative value in the 
case of an error. 


SetSelStrings 

int SetSelStrings(const char far** prefixes, int numSelections, bool shouldSet); 

For multiple-selection list boxes, selects the strings in the associated list box that begin 
with the prefixes specified in the prefixes array. For each string, the search begins at the 
beginning of the list and continues until a match is found or until the list has been 
completely traversed. If shouldSet is true, the matched strings are selected and 
highlighted; if shouldSet is false the highlight is removed from the matched strings and 
they are no longer selected. Returns the number of strings successfully selected or 
deselected (—1 for single-selection list boxes and combo boxes). If numSelections is less 
than 0, all strings are selected or deselected, and a negative value is returned on failure. 


SetTabStops 

bool SetTabStops(int numTabs, int far* tabs); 

Sets tab stops. numTabs is the number of tabstops. tabs is the array of integers 
representing the tab positions. 


SetTopindex 
int SetTopindex(int index); 
Sets index to the first item displayed at the top of the list box. 


Seealso TListBox::GetTopIndex 


Transfer 
uint Transfer(void *buffer, TTransferDirection direction); 
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Transfers the items and selection(s) of the list box to or from a transfer buffer if tdSetData 
or tdGetData, respectively, is passed as the direction. buffer is expected to point to a 
pointer to a TListBoxData structure. 


Transfer, which overrides the TWindow virtual member function, returns the size of 
TListBoxData (the pointer, not the structure). To retrieve the size without transferring 
data, pass tdSizeData as the direction. 


You must use a pointer in your transfer buffer to these structures. You can't embed 
copies of the structures in your transfer buffer, and you can't use these structures as_ 
transfer buffers. 


See also TListBoxData, TWindow::Transfer 


Protected member function 


GetClassName 
char far* GetClassName(); 
Returns the name of TListBox's registration class, "LISTBOX". 


Used to transfer the contents of a list box. 


Public data members 


ltemDatas 
TDwordArray* ItemDatas; 
Contains all uint32 item data for each item in the list box. 


SelCount 
int SelCount; 
Holds the number of selected items. 


_ Selindices 
_ TIntArray* Sellndices; 
Contains the indexes of all the selected strings in a multiple-selection list box. 


SelStrings 

TStringArray* SelStrings; 

Pointer to an array of the strings to select when ane is transferred into the list box. 
When data is transferred out of the list box, SelStrings returns the current selection(s). 


Strings 
TStringArray* Strings; 
Pointer to an array of strings to be transferred into a TListBox. 
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Public constructor and destructor 


Constructor 
TListBoxData(); 
Constructs Strings and SelStrings. Initializes SelCount to 0. 


Destructor 
~TListBoxData(); 
Deletes the space allocated for Strings and SelStrings. 


Public member functions 


AddString 

void: AddString(const char *str, bool isSelected = false); 

Adds the specified string to Strings. If IsSelected is true, adds the string to SelStrings and 
increments SelCount. 


AddStringltem 

void AddStringltem(const char* str, uint32 itemData, bool isSelected = false)); 

Adds a string to the Strings array, optionally selects it, and adds item data to the 
[temDatas array. 


Clear 

void Clear(); 

Resets the list box by flushing the ItemDatas are Strings arrays and calling 
ResetSelections. 


Seealso TListBoxData::Strings, TListBoxData::ItemDatas, 
TListBoxData::ResetSelections 


GetltemDatas 
TDwordArray& GetltemDatas(); 
Returns a pointer to the ItemDatas array. 


See also TListBboxData::ItemDatas 


GetSelindices 
TintArray& GetSellndices(); 
Returns a pointer to the SelIndices array. 


See also TListBoxData::SelIndices 


GetSelString 

void GetSelString(char far* buffer, int bufferSize, int index = 0) const; 

Locates the string at the specified index in SelStrings and copies it into buffer. bufferSize 
includes the terminating NULL. 


GetSelStringLength 

int GetSelStringLength(int index = 0) const; 

Returns the length (excluding the terminating NULL) of the string at the specified index 
in SelStrings. 
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GetStrings | 
TStringArray& GetStrings(); 
Returns a pointer to the Strings array. 


See also TListBoxData::Strings 


ResetSelections 
void ResetSelections(); 
Removes all strings from SelStrings and sets SelCount to 0. 


Select 
void Select(int index); 
Selects the string at the given index. 


SelectString 
void SelectString(const char far* str); 
Adds str to SelStrings and increments SelCount. 


TListView class — : listview.h 


Derived from TListBox and TView, TList View provides views for list boxes. See TView for 
a description of view functions and TListBox for list box functions. 


Public constructor and destructor 


Constructor 

TListView(TDocument& doc, TWindow* parent = 0); 

Creates a TListView object associated with the specified document and parent window. 
Sets Attr.AccelTable to IDA_LISTVIEW to identify the edit view. Sets the view style to 
WS_HSCROLL | LBS_NOINTEGRALHEIGHT. 


Sets TView::ViewMenu to the new TMenuDescr for this view. 


Destructor 

~TListView(); 

After checking to see if there is an epee view, this destructor destroys the TList View 
object. 


Public data member 
DirtyFlag_ 


bool DirtyFlag; 
Is nonzero if the data in the list view has been changed; otherwise, is 0. 
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Public member functions 


CanClose 

bool CanClose(); 

Checks to see if all child views can be closed before closing the current view. If any child 
returns 0, CanClose returns 0 and aborts the process. If all children return nonzero, it 
calls TDocManager::FlushDoc. 


See also TDocManager::FlushDoc 


Create 

virtual bool Create(); 

Overrides TWindow::Create and creates the view's window. Determines if the file is new 
or already has data. If there is data, calls LoadData to add the data to the view. If the 
view's window can't be created, Create throws a TXInvalidWindow exception. 


GetViewName 

const char far* GetViewName(); 

Overrides TView’s virtual function and returns the descriptive name of the class 
(StaticName). 


Seealso TView::GetViewName 


GetWindow 
TWindow* GetWindow(); 
Overrides TView’s virtual function and returns the list view object as a TWindow. 


Seealso TView::GetWindow 


SetDocTitle 

bool SetDocTitle(const char far* docname, int index); 

Overrides TView's virtual function and stores the document title. This name is 
forwarded up the parent chain until a TFrameWindow object accepts the data and 
displays it in its caption. 

Seealso TView::SetDocTitle 


StaticName 

static const char far* StaticName(); 

Overrides TView's function and returns a constant string, "ListView." This information is 
displayed in the user interface selection box. 


Seealso T'View::GetViewName 


Protected data members 


MaxWidth 

int MaxWidth; 

Holds the maximum horizontal extent (the number of pixels by which the view can be 
scrolled horizontally). 


Chapter 2, ObjectWindows library reference 273 


TListView class 


Origin © 
long Origin; 
Holds the file position at the beginning of the signi 


Protected member functions 


CmEditAdd 

void CmEditAdd(); 

Automatically responds to CM_LISTADD message by getting the length of the input 
string and calling InsertString to insert the text string into the list view. Sets the data 
member DirtyFlag to true. 


CmEditClear 

void CmEditClear(); 

Automatically responds to a menu selection with a menu ID of CM_EDITCLEAR by 
clearing the items in the list box using functions in TListBox. 


CmEditCopy 

void CmEditCopy(); 

Automatically responds to a menu selection with a menu ID of CM _EDITCOPY and 
copies the selected text to the Clipboard. 


CmEditCut 

void CmEditCut(); 

Automatically responds to a menu csinction with a menu ID of CM_EDITCUT by 
calling CmEditCopy and CmEditDelete to delete a text string from the list view. Sets the 
data member DirtyFlag to true. 


CmEditDelete 

void CmEditDelete(); 

Automatically responds to a menu selection with a menu ID of CM_EDITDELETE and 
deletes the selected text. | 


CmEditltem 

void CmEditltem(); | 
Automatically responds to a CM_LISTEDIT message by getting the input text and 
inserting into the list view. Sets the DirtyFlag to nonzero to indicate that the view ae 
been changed and not saved. 


CmEditPaste 

void CmEditPaste(); 

Automatically responds to a menu selection with a menu ID of CM_ EDITPASTE by 
inserting text into the list box using functions in TListBox. 


CmEditUndo 

void CmEditUndo(); 

Automatically responds to a menu selection with a menu ID of CM_EDITUNDO by 
calling TListBox::Undo. 
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CmSelChange 

void CmSelChange(); 

Automatically responds to a LBN_SELCHANGE message (which indicates that the 
contents of the list view have changed) by calling DefaultProcessing. 


EvGetDigCode 

uint EvGetDigCode(MSG far* msg); 

Overrides TWindow’s response to a WM_GETDLGCODE message (an input procedure 
associated with a control that isn't a check box) by calling DefaultProcessing. The msg 
parameter indicates the kind of message, for example a control or a command message, 
sent to the dialog box manager. 


EvGetDIgCode returns a code that indicates how the list box control message is to be 
treated. 3 


Seealso TButton::EvGetDlgCode, TWindow::DefaultProcessing, DLGC_xxxx dialog 
control message constants 


LoadData 

bool LoadData(int top, int sel); 

Reads the view from the stream and closes the file. Returns true if the view was 
successfully loaded. 


Throws an xmsg exception and displays the error message "TListView initial read error" 
if the file can't be read. Returns false if the view can't be loaded. 


SetExtent 
void SetExtent(LPSTR str); 
Sets the maximum horizontal extent for the list view window. 


VnCommit 

bool VnCommit(boo! force); 

VnCommit commits changes made in the view to the document. If force is nonzero, all 
data, even if it's unchanged, is saved to the document. 


Seealso TListView::vnRevert, vnxxxx view notification constants 


VnDocClosed 
bool VnDocClosed(int omode); 
VnDocClosed indicates that the document has been closed. 


See also vnxxxx view notification constants 


VnisDirty 

bool VnisDirty(); 

VnIsDirty returns nonzero if changes made to the data in the view have not been saved 
to the document; otherwise, returns 0. 


See also} vnxxxx view notification constants 
VnisWindow 
bool VnisWindow(HWND hWnd); 


VnIsWindow returns nonzero if the window's handle passed in hWnd is the same as that 
of the view's display window. 
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See also vnxxxx view notification constants 


~ VnRevert 
bool VnRevert(bool clear); 
VnRevert indicates if changes made to the view should be erased, and the data from the 
document should be restored to the view. If clear is nonzero, the data is cleared instead 
of restored to the view. 


See also PiskViswen Comat 


Response table entries 


BV i z 
EV_COMMAND(CM_LISTCUT, CmEditCut) CmEditcut 


EV_COMMAND(CM_LISTCOPY, CmEditCopy) CmEditCopy 
EV_COMMAND(CM_LISTPASTE, CmEditPaste) CmEditPaste 
EV_COMMAND(CM_LISTCLEAR, CmEditClear) CmEditClear 
EV_COMMAND(CM_LISTDELETE, CmEditDelete) _ CmkditDelete 
EV_COMMAND(CM_LISTADD, CmEditAdd) CmEditAdd 
EV_COMMAND(CM_LISTEDIT, CmEditItem) CmEditltem 
EV_WM_GETDLGCODE EvGetDlgCode 
EV_NOTIFY_AT_CHILD(LBN_DBLCLK, CmEditItem) CmEditItem 
EV_NOTIFY_AT_CHILD(LBN_SELCHANGE, CmSelChange) | CmSelchange 
EV_VN_DOCCLOSED VnDocClosed 
EV_VN_ISWINDOW | VnlsWindow 
EV_VN_ISDIRTY VnlsDirty 
_EV_VN_COMMIT | VnCommit 
EV_VN_REVERT VnRevert 
TLocaleString struct - -locale.h 


Designed to provide support for localized registration parameters, the TLocaleString 
struct defines a localizable substitute for char* strings.These strings, which describe 
both OLE and non-OLE enabled objects to the user, are available in whatever language 
the user needs. This struct supports ObjectWindows' Doc/View as well as 
ObjectComponents, OLE-enabled applications.The public member functions, which — 
supply information about the user's language, the native language, and a description of 
the string marked for localization, simplify the process of translating and comparing 
strings in a given language. 


To localize the string resource, TLocaleString uses several user-entered prefixes to 
determine what kind of string to translate. Each prefix must be followed by a valid 
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resource identifier (a standard C identifier). The following table lists the the prefixes 
TLocaleString uses to localize strings. Each prefix is followed by a sample entry. 


tring is ries of characters interpreted resource ID and is acces 


resource file. It is never used directly. 


#1045 The string is a series of digits interpreted as a resource ID and is accessed from a resource 
file. It is never used directly. 


!MyWindow The string is translated if it is not in the native language; otherwise, this string is used 
directly. 


See the section on localizing symbol names in the Object Windows Programmer's Guide for 
more information about localizing strings. 


Public member functions 


Compare 

int Compare(const char far* str, TLangld lang); 

Using the specified language (lang), Compare compares TLocaleString with another 
string. It uses the standard string compare and the language-specific collation scheme. It 
returns one of the following values. — 


ere 1S NO matc 


etween the two strings. 
1 ~~ ~___ This string is greater than the other string. 
-1 This string is less than the other string. 
GetSystemLangld 


static TLangld GetSystemLangld(); 
Returns the system language ID, which can be the same as the UserLangld. 


Seealso TLocaleString::GetUserLangld 


GetUserLangld 

static TLangld GetUserLangld(); 

Returns the user language ID. For single user systems, this is the same as 
LangSysDefault. The language ID is a predefined number that represents a base language 

and dialect. 


Seealso TLocaleString::GetSystemLangld 
IsNativeLangld 


Static int IsNativelangld(TLangld lang); 
Returns true if lang equals the native system language. 


operator const char* 
operator const char* (); 
Returns the current character string in the translation. 
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operator = = 
void operator = (const char* str); 
Assigns the string (str) to this locale sin 


Translate 

const char* Translate(TLangld lang); 

Translates the string to the given fanenaee Translate follows this order of preienee: in 
order to choose a language for translation: 


1 Base language and dialect. 
Base language and no dialect 
Base language and another dialect 


The native language of the resource itself. 


oi & Gd PND 


Returns 0 if unable to translate the string. (This can happen only if an @ or # prefix is 
used; otherwise, the ! prefix indicates that the string following is the native language 
itself.) 


Seealso TLangld typedef, LangXxxx_ID constants 


A streamable class, TLookupValidator compares the string typed by a user with a list of 
acceptable values. TLookupValidator is an abstract validator type from which you can 
derive useful lookup validators. You will never create an instance of TLookupValidator. 
When you create a lookup validator type, you need to specify a list of valid items and 
override the Lookup method to return true only if the user input matches an item in that 
list. One example of a working descendant of TLookupValidator is 

TStringLookup Validator. 


Publicconstructor 


Constructor 
TLookupValidator(); 
Constructs a TLookupValidator object. 


Public member functions 


_ IsValid 
bool IsValid(const char far* str); | 
IsValid overrides TValidator’s virtual function and calls Lookup to find the string str in the 
list of valid input items. IsValid returns true if Lookup returns true, meaning Lookup 
found str in its list; otherwise, it returns false. 


Lookup 
virtual bool Lookup(const char far* str); 
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Searches for the string str in the list of valid entries and returns true if it finds str; 
otherwise, returns false. TLookupValidator’s Lookup is an abstract method that always 
returns false. Descendant lookup validator types must override Loop to perform a 
search based on the actual list of acceptable items. 


Form 1 


Form 2 


TMDIChild defines the basic behavior of all MDI child windows. Child windows can be 
created inside the client area of a parent window. Because child windows exist within, 
and are restricted to the parent window's borders, the parent window defined before 
the child is defined. For example, a dialog box is a window that contains child windows, 
often referred to as dialog box controls. 


To be used as MDI children, classes must be derived from TMDIChild. MDI children can 
inherit keyboard navigation, focus handling, and icon support from TFrameWindow. 
TMDIChild is a streamable class. 


Public constructors and destructor 


Constructors 

TMDIChild(TMDIClient& parent, const char far* title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, 
TModule* module = 0); 

Creates an MDI child window of the MDI client window specified by parent, using the 

specified title, client window (clientWnd) and instance (inst). Invokes the TFrameWindow 

base class constructor, supplying parent, title, cllentWnd, inst, and indicating that the 

child window is not to be resized to fit. Invokes the TWindow base class constructor, 

specifying parent, title, and inst. The window attributes are then adjusted to include 

WS_VISIBLE, WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, _ 

WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and 


~ WS_MAXIMIZEBOX. The dimensions of the window are set to the system default 


values. 


TMDIChild(HWND hWnd, TModule* module = 0); 

Creates an MDI child window object from a preexisting window, specified by hWnd. 
The base class TFrameWindow constructor is invoked, specifying this hWnd, as well as 
the specified inst. The base class TWindow constructor is invoked, supplying the hWnd 
and inst parameters. 


Destructor 
~TMDIChild(); 
Destructs the MDI child window object. 


Public member functions 


Destroy 


void Destroy(retVal = 0); 
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Destroys the interface element associated with the TMDIChild. Calls EnableAutoCreate 
for each window in the child list so that the children are also re-created when the parent 
window is re-created. . | 


See also TWindow:EnableAutoCreate 3 


EnableWindow 
bool EnableWindow(bool enable); _ | 
Overrides TWindow’s virtual function. Enables a child window. 


PreProcessMsg 

bool PreProcessMsg (MSG& msq); | 
Performs preprocessing of window messages for the MDI child window. If keyboard 
handling is enabled the parent client window's TMDIClient_PreProcessMsg member 
function is called to preprocess messages. In this case, the return value is true. 
Otherwise, TFrameWindow::PreProcessMsg is called and its return value becomes the 
return value of this member function. 


Seealso TMDIClient::PreProcessMsg, TFrameWindow::PreprocessMsg 


ShowWindow — 

bool ShowWindow(int cmdShow); 

Overrides TWindow’s virtual function. Displays a child window according to the value 
of cmdShow. 


Protected member functions 


DefWindowProc 
LRESULT DefWindowProc (uint msg, WPARAM wParam, LPARAM Param) 
Overrides TWindow::DefWindowProc to provide default processing for any incoming 

_ message the MDI child window does not process. In addition, DefWindowProc handles 
the following messages: WM_CHILDACTIVATE, WM_GETMINMAXINEFO, 
WM_MENUCHAR, WM_MOVE, WM_SETFOCUS, WM_SIZE, and 
WM_SYSCOMMAND. 


See also TWindow::DefWindowProc 


EvMD1Activate 

void EvMDIActivate(HWND hWndActivated, HWND 1WndDeactivated) 

Instructs a client window to activate or deactivate an MDI child window and then sends 
a message to the child window being activated and the child window being deactivated. 


EvNCActivate 
void EvNCActivate(bool activate); 
Responds to a request to change a title bar or icon. 


PerformCreate 

void PerformCreate(int menuOrld); | 
Creates the interface element associated with the MDI child window. The supplied 
menuOrlId parameter is ignored because MDI child windows cannot have menus. 
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Response table entries 


-EV_WM MDIACTIVATE — EvMDIActivate 
EV_WM_NCACTIVATE — EvNCActivate 


Linh 


Multiple Document Interface (MDI) client windows (represented by a TMD Client 
object) manage the MDI child windows of a TMD IFrame parent. TMDIClient is a 
streamable class. 


Public constructor and destructor 


Constructor 

TMDIClient(TModule* module = 0); 

Creates an MDI client window object by invoking the base class TWindow constructor, 
passing it a null parent window, a null title, and the specified library ID. Sets the default 
client window identifier (IDW_MDICLIENT) and sets the style to include 
MDIS_ALLCHILDSTYLES, WS_GROUP, WS_TABSTOP, WS_CLIPCHILDREN, 
WS_VSCROLL, and WS_HSCROLL. Initializes the ClientAttr data member, setting its 
idFirstChild member to IDW_FIRSTMDICHILD. 


Destructor 
~TMDIClient(); 
Frees the ClientAttr structure. 


Seealso TWindow::TWindow, TWindow::~TWindow 
Public data member 
ClientAttr 


LPCLIENTCREATESTRUCT ClientAttr; 
ClientAttr holds a pointer to a structure of the MDI client window's attributes. 


Public member functions 
Arrangelcons 


virtual void Arrangelcons(); 
Arranges the MDI child window icons at the bottom of the MDI client window. 
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CascadeChildren 

_ virtual void CascadeChildren(); 

_ Sizes and arranges all of the non-iconized MDI child maniowe pene the MDI client 
window. The children are overlapped, although each title bar is visible. — 


CloseChildren 

virtual boo! CloseChildren(); 

First calls CanClose on each of the MDI child windows oie by this MDI client. 
Returns true if all MDI children are closed; otherwise returns false. 


See also TWindow::CanClose 


Create 

bool Create(); 

Creates the interface element associated with the MDI client window. Calls 
TWindow::Create after first setting the child window menu in ClientAttr to the parent 
frame window's child menu. 


Seealso TWindow_Create, TFrameWindow_GetMenuDescr 


CreateChild 

virtual TWindow* CreateChild(); | | 

Overrides member function defined by TWindow. Constructs and creates a new MDI 
child window by calling InitChild and Create. Returns a pointer to the new MDI child 
window. 


Seealso TMDIClient::InitChild, TModule:MakeWindow, TWindow::Create _ 


GetActiveMDIChild 

TMDIChild *GetActiveMDIChild(): | 
GetActiveMDIChild points to the TMDIClient’s active MDI child window. 
GetActiveMDIChild is set by the child in its EvpMDIActivate message response member 
function. TMD!IClient's constructors initialize GetActiveChild. 


InitChild © 

virtual TMDIChild *InitChild(); | 

Constructs an instance of TWindow as an MDI child window and returns a pointer to it. 
Children must be created with MDI client as the parent window. Redefine this member 
function in your derived MDI window class to construct an instance of a derived MDI 
child class. For example, 


- PTWindowsObject TMyMDIClient::InitChild() 


{ 
return new TMyMDIChild(this, ""); 
} ; 


Seealso TMDIClient::CreateChild 
PreProcessMsg 
bool PreProcessMsg(MSG &msgq); 


If the specified msg is one of WM_KEYDOWN or WM_ SYSKEYDOWN, then the 
keyboard accelerators are translated for the MDI client. 


See also TWindow::PreProcessMsg 


282 ObjectWindows Reference Guide 


TMDIClient class 


TileChildren 

virtual void TileChildren(int tile = MDITILE VERTICAL); 

Sizes and arranges all of the non-iconized MDI child windows within the MDI client 
window. The children fill up the entire client area without overlapping. 


Seealso TMDI]Client::TileChildren 


Protected member functions 


CmArrangelcons 

void CmArrangelcons(); 

Calls Arrangelcons in response to a menu selection with an ID of 
CM_ARRANGEICONS. | 


Seealso TMDI[Client::Arrangelcons 


CmCascadeChildren 

void CmCascadeChildren(); 

Calls CascadeChildren in response to a menu selection with an ID of 
CM_CASCADECHILDREN. 


Seealso TMDI]Client::CascadeChildren 


CmChildActionEnable 

void CmChildActionEnable(T CommandEnabler& commandEnabler); 

If there are MDI child windows, CmChildActionEnable enables any one of the child 
window action menu items. 


CmCloseChildren 

void CmCloseChildren(); 

Calls CloseChildren in response to a menu selection with an ID of 
CM_CLOSECHILDREN. 


See also TMDIClient::CloseChildren 
CmCreateChild 
void CmCreateChild(); 


Calls CreateChild to produce a new child window in response to a menu selection with a 
menu ID of CM_CREATECHILD. 


See also TMDI]Client::CreateChild 


CmTileChildren 
void CmTileChildren(); 
Calls TileChildren in response to a menu selection with an ID of CM_TILECHILDREN. 


See also TMD!IClient::TileChildren 
CmTileChildrenHoriz _ 
void CmTileChildrenHoriz(); 


Calls TileChildren in response to a menu selection with an ID of CM_TILECHILDREN 
and passes MDI child tile flag as MDITILE_HORIZONTAL. 
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EvMDICreate | 

LRESULT EvMDICreate(MDICREATESTRUCT far& createStruct); 

Intercepts the WM_MDICREATE message sent when MDI child windows are created, 
and, if the client's style includes MDIS_ALLCHILDSTYLES, and the child window's 
specified style is 0, then changes the child window style attributes to WS_VISIBLE, 
WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, WS_SYSMENU, 
WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX. 


See also TWindow::DefaultProcessing, MDICREATE struct 


EvMDIDestroy 
void EvMD!Destroy(HWND hWnd); 
Intercepts the WM_MDIDESTROY message. 


- GetClassName 
char far *GetClassName(); 
Returns TMD!IClient’s registration class name, "MDICLIENT." 


Response table entries 


SEtCo | § 
EV “COMMAND (CM. CASCADECHILDREN, CmCascadeChildren) CmCascadeChildren | 
EV_COMMAND (CM_CLOSECHILDREN, CmCloseChildren) CmCloseChildren 
EV_COMMAND (CM_CREATECHILD, CmCreateChild) — CmCreateChild 
EV_COMMAND (CM_TILECHILDREN, CmTileChildren) CmTileChildren 
EV_COMMAND(CM_TILECHILDRENHORIZ,CmTileChildrenHoriz) CmTileChildrenHoriz 
EV_COMMAND._ ENABLE(CM_TILECHILDREN, CmChildActionEnable) CmcChildActionEnable 
EV_COMMAND_ENABLE(CM_CASCADECHILDREN, CmChildActionEnable 
CmChildActionEnable) 


EV_COMMAND_ENABLE(CM_ARRANGEICONS, CmChildActionEnable) CmChildActionEnable 
EV_COMMAND._ ENABLE(CM_CLOSECHILDREN, CmChildActionEnable) CmChildActionEnalbe 


EV_WM_MDICREATE EvMD!]Create 
EV_WM_MDIDESTROY | EvMD Destroy 
TMDiFrame class — | mdi.h 


Multiple Document Interface (MDI) frame windows, represented by TMD IFrame, are 
overlapped windows that serve as main windows of MDI-compliant applications. . 
TMD IFrame objects automatically handle the creation and initialization of an MDI client 
"window" (represented by a TMD!IClient object) required by Windows. TMD IFrame sets 
window style WS_CLIPCHILDREN by default so that minimal flicker occurs when the 
MDI frame erases its background and the backgrounds of its children. TMDIFrame is a 

_ streamable class. 
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Because TMD IFrame is derived from TFrameWindow, it inherits keyboard navigation. As 
a result, all children of the MDI frame acquire keyboard navigation. However, it's best to 
enable keyboard navigation only for those children who require it. 


To create an OLE-enabled MDI frame window, use TOleMDIFrame, which inherits 
functionality from both TMD IFrame and and TOleFrame. 


See also 
TOLEMDIFrame 


Public constructors 


Constructors 
TMDIFrame(const char far *title, TResld menuResid, TMDIClient &clientWnd = *new TMD!IClient, 

TModule* module = 0); 
Constructs an MDI frame window object using the caption (title) and resource ID 
(menuResId). If no client window is specified (clientWnd), then an instance of TMDIClient 
is created automatically and used as the client window of the frame. The supplied 
library ID (module) is passed to the TFrameWindow constructor along with a null parent 
window pointer, caption, client window, and a flag indicating that the client window is 
not to be resized to fit. The TWindow constructor is also invoked; it passes the supplied 
caption and library ID, as well as a null parent window pointer. Then the child menu 
position is initialized to be the leftmost menu item, and the supplied menu resource ID 
is used in a call to AssignMenu. 


TMDIFrame(HWND hWindow, HWND clientHWnd, TModule* module = 0); 

Constructs an MDI frame window using an already created non-ObjectWindows 
window. Invokes the TFrameWindow TWindow constructors passing in the window 
handle (hWindow) library ID (module). Initializes the child menu position to the leftmost 
menu item and constructs a TMD!IClient object that corresponds to the supplied 
clientHWnd. 


See also TFrameWindow::AssignMenu, TFrameWindow::TFrameWindow, 
TMDiIClient:: TMDIClient, TWindow::TWindow 


Public member functions 


FindChildMenu 

static HMENU FindChildMenu(HMENU newMenu); 

FindChildMenu searches, from right to left, the pop-up child menus contained in the 
newMenu menu resource for a child menu containing command items with one of the 
following identifiers: CM_CASCADECHILDREN, CM_TITLECHILDREN, or 
CM_ARRANGEICONS. The return value of FindChildMenu is the HMENU of the first 
child menu containing one of these identifiers. If one of these identifiers is not found, 
FindChildMenu returns 0. 


FindChildMenu is used to locate the menu to which the MDI child window list will be 
appended. This call to FindChildMenu is made from within the TMD!IClient class. 
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GetClientWindow 
TMDIClient *GetClientWindow(); 
Returns a pointer to the MDI client window. — 


See also TFrameWindow::GetClientWindow 


GetCommandfarget 

virtual HWND GetCommandTarget(); 

Locates and returns the child window that is the target of the command and command 
enable messages. If the current application does not have focus or if the focus is within a 
toolbar in the application, GetCommandTarget returns the most recently active child _ 
window. If an alternative form of command processing is desired, a user's main 
window class can override this function. 


PerformCreate 

void PerformCreate(int menuOrld); 

Overrides TWindow's virtual function. Creates me interface element associated with the 
MDI frame window. 


SetMenu 

bool SetMenu (HMENU); 

Looks for the MDI submenu in the new menu bar. Searches for the MDI child menu in 
the new menu bar and updates the child menu position with the specified menu index. 
Then sends the client window an WM_MDISETMENU message to set the new menu 
and invokes TWindow::DrawMenuBar to redraw the menu. Returns false if the MDI 
client indicates that there was no previous menu; otherwise, returns true. 


Seealso TWindow::DrawMenuBar 


Protected member functions 


DefWindowProc | 

LRESULT DefWindowProc (uint message, WPARAM wParam, LPARAM IParam); 

Overrides TWindow::DefWindowProc and provides default processing for any incoming 
message the MDI frame window does not process. 


See also TWindow::DefWindowProc 


Response table entries 


The TMD IFrame response table has no entries. 


_. TMeasurementUnits enum | layoutco.h 


enum TMeasurementUnits{lmPixels,lmLayoutUnits}; 

Used by the TLayoutConstraint struct, TMeasurementUnits enumerates the measurement 
units (ImPixels or ImLayoutUnits) that control the dimension of the window. These can be - 
either pixels or layout units that are obtained by dividing the font height into eight 
vertical and eight horizontal ee 
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Seealso T’LayoutConstraint struct 


TMemoryDC class 


A DC class derived from TDC, TMemoryDC provides access to a memory DC. 


Public constructors 


Constructors 
Form1 TMemoryDC(); 
Default constructor for a memory DC object. 


Form 2 TMemoryDC(const TDC& DC); 
Creates a memory DC object compatible with the given DC argument. 


Form3 TMemoryDC(HDC handle, TAutoDelete AutoDelete); 
Creates a memory DC object from an existing DC handle. 


Seealso TDC::TDC 


Public member functions 


RestoreBitmap 
void RestoreBitmap(); 
Restores the originally selected bitmap object for this DC. 


See also 9 TDC::RestoreObjects 


RestoreQObjects 
void RestoreObjects(); 


de.h 


Restores the originally selected brush, pen, font, palette, and bitmap objects for this DC. 


See also TDC::RestoreObjects, TMemoryDC::RestoreBitmap 


SelectObject 

void SelectObject(const TBrush& brush); 

void SelectObject(const TPen& pen); 

void SelectObject(const TFont& font); 

void SelectObject(const TPalette& palette, bool forceBackground=false); 
void SelectObject(const TBitmap& bitmap); 

Selects the given GDI object into this DC. 


See also TDC::SelectObject, TMemoryDC::RestoreBitmap, 
TMemoryDC::RestoreObjects 


Protected data member 


OrgBitmap 
HBITMAP OrgBitmap; © 
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The original bitmap selected into this DC. 
See also TMemoryDC::SelectObject, TMemoryDC::RestoreBitmap 


TMenuclass a menu.h 


Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


Form 6 


Form 1 


The TMenu class encapsulates window menus. You can use TMenu member functions to 
construct, modify, query, and create menu objects. You can also use TMenu to add 
bitmaps to your menu or to specify if a menu item is checked or unchecked. TMenu 
includes two versions of a helper function, DeepCopy, designed to make copies of menus 
and insert them at a specified position on the menu bar. See the Object Windows 
Programmer's Guide for information about how to create menu objects. 


Public constructors and destructor 


Constructors 

TMenu(TAutoDelete autoDelete = AutoDelete); 

Creates an empty menu and sets autoDelete, by default, so that the menu is automatically 
deleted when the object is destroyed. 


TMenu(const TMenu& original, TAutoDelete autoDelete = NoAutoDelete); 
Creates a complete copy of an existing menu and sets autoDelete, by default, so that the 
menu is not automatically deleted when the object is destroyed. 


TMenu(HWND wnd, TAutoDelete autoDelete = NoAutoDelete):; 
Creates a menu object representing the window's current menu and sets autoDelete, by 
default, so that the menu is not automatically deleted when the object is destroyed. 


TMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete); 
Creates a menu object from an already loaded menu and sets autoDelete, by default, SO 
the menu is not automatically deleted when the object is destroyed. 


TMenu(const void far* menuTemplate); | 
Creates a menu object from a menu template in memory. This constructor is not 
available under Presentation Manager. | 


TMenu(HINSTANCE instance, TResid resld); 
Creates a menu object from a specified resource ID. 


Destructor 
virtual ~TMenu(); 


Destroys the menu. 


Seealso TResld class 


Public member functions 


AppendMenu 
bool AppendMenu(uint flags, uint newltem, const TBitmap& newBmp); | 
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Adds a bitmap menu item at the end of the menu. See TMenu::GetMenuState for a 
description of the flag values that specify the attributes of the menu, for example, menu 
item is checked, menu item is disabled, and so on. 


bool AppendMenu(uint flags, uint newltem = —1, const char far* newltem = 0); 

Adds a text menu item to the end of the menu. See TMenu::GetMenuState for a 
description of the flag values that specify the attributes of the menu, for example, menu 
item is checked, menu item is a a bitmap, and so on. 


See also TBitmap class, TMenu::GetMenuState 


CheckMenultem 

bool CheckMenultem(uint item, uint check); 

Checks or unchecks the menu item. By combining flags with the bitwise OR operator 
(|) check specifies both the position of item (MF_BYCOMMAND, MF_BYPOSITION) 
and whether item is to be checked (MF_CHECKED) or unchecked (MF_UNCHECKED). 


CheckValid 
void CheckValid(uint resid = IDS_MENUFAILURE); 
Throws a TXMenu exception if the menu object is invalid. 


See also TMenu::TXMenu 


DeleteMenu 

bool DeleteMenu(uint item, uint flags); 

Removes the menu item (item) from the menu or deletes the menu item if it's a pop-up 
menu. flags is used to identify the position of the menu item by its relative position in the 
menu (MF_BYPOSITION) or by referencing the handle to the top-level menu | 
(ME_BYCOMMAND). 


Seealso —TMenu::RemoveMenu 


Drawitem 

virtual void Drawltem(DRAWITEMSTRUCT far& drawltem); 

Drawltem responds to a message forwarded to a drawable control by TWindow when the 
control needs to be drawn. 


See also DRAWITEMSTRUCT struct 


EnableMenultem 

bool EnableMenultem(uint item, uint enable); 

Enables, disables, or grays the menu item specified in the item parameter. If a menu item 
is enabled (the default state), it can be selected and used as usual. If a menu item is 
grayed, it appears in grayed text and cannot be selected by the user. If a menu item is 
disabled, it is not displayed. Returns true if successful. 


GetHandle 
virtual HMENU GetHandle(); 
Returns the handle to the menu. 


Seealso TMenu::IsOK 


GetMenuCheckMarkDimensions 
static bool GetMenuCheckMarkDimensions(TSize& size); 
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Gets the size of the bitmap used to ey: the default checkmark on. heeked menu 
items. 


See also TMenu::SetMenultemBitmaps, TSize class 


GetMenultemCount 
uint GetMenultemCount() const; | 
Returns the number of items in a top-level or pop-up menu. 


GetMenultemID 

_uint GetMenultemID(int posltem) const; 
Returns the ID of the menu item at the position specified by pos! tem. If this is a pop-up 
menu, returns the ID of the menu’s first item minus one. 


GetMenuState 

- uint GetMenuState(uint item, uint flags) const; 
Returns the menu flags for the menu item specified by item. flags specifies how the item 
is interpreted, and is one of the following values: 


erpret item as a menu comman 
MF_BYPOSITION is specified. 


MF_BYPOSITION sli item as the zero-base relative postion of the menu item within the menu. 


nor 


If item is found, and - a pop-up menu, the low-order byte of the return value contains 
the flags associated with item, and the high-order byte contains the number of items in 
_ the pop-up menu. If item is not a pop-up menu, the return value specifies a combination 


of these flags: 

MF_BITMAP Menu item is a a bitmap. 

MF_CHECKED Menu item is checked (pop-up menus only). 

MF_DISABLED Menu item is disabled. 

-MF_ENABLED Menu item is enabled. Note: this constant's value is 0. 

MF_GRAYED Menu item is disabled and grayed. 

MF_MENUBARBREAK Same as MF_MENUBREAK except pop-up menu columns are opens bya 
vertical dividing line. 

MF_MENUBREAK Static menu items are placed on a new line, pop-up menu items are placed in a 
new column, without separating columns. 

MF_SEPARATOR A horizontal dividing line is drawn, which cannot be enabled, checked, grayed, 

| or highlighted. Both item and flags are ignored. 
MF_UNCHECKED ~~ Menu item check mark is removed (default). Note: this constant value is 0. 


Returns —1 if item doesn't exist. 
GetMenuString 


uint GetMenuString(uint item, char* str, int count, uint flags) const; 
Returns the label (str) of the menu item (item). 
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GetSubMenu 
HMENU GetSubMenu(int posltem) const; 
Returns the handle of the menu specified by posltem. 


InsertMenu 

bool InsertMenu(uint item, uint flags, uint newltem, const TBitmap& newBmp); 

Adds a bitmap menu item after the menu item specified in item. The flags parameter 
contains either the MF BYCOMMAND or MF_BYPOSITION values that indicate how 
to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if 
MF_BYPOSITION, item holds a relative position within the menu. 


bool InsertMenu(uint item, uint flags, uint newltem =—1, const char far* newltem = 0); 

Inserts a new text menu item or pop-up menu into the menu after the menu item 
specified in item. The flagsparameter contains either the MF_BYCOMMAND or 
MF_BYPOSITION values that indicate how to interpret the item parameter. If 

MF BYCOMMAND, item is a command ID; if MF _BYPOSITION, item holds a relative 
position within the menu. 


Seealso ~TMenu::GetMenuState 


IsOK 
bool IsOK() const; ‘ 
Returns true if the menu has a valid handle. 


See also TMenu::GetHandle 


Measureltem 

virtual void Measureltem(MEASUREITEMSTRUCT far& measureltem); 

measureltem is used by owner-drawn controls to store the dimensions of the specified 
item. 


See also MEASUREITEMSTRUCT struct 


ModifyMenu 

bool ModifyMenu(uint item, uint flags, uint newltem, const TBitmap& newBmp):; 

Changes an existing menu item into a bitmap. The flags parameter contains either the 
MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item 
parameter. If MF_ BYCOMMAND, item is a command ID; if MF_BYPOSITION, item 
holds a relative position within the menu. 


bool ModifyMenu(uint item, uint flags, uint newltem = —1, const char far* newltem = 0); 

Changes an existing menu item from the item specified in item to newltem. The flags 
parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that 
indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a 
command ID; if MF_BYPOSITION, item holds a relative position within the menu. 


Seealso TMenu::GetMenuState 


operator HMENU() 
operator HMENU(); 
Returns the menu's handle. 


See also ‘Menu::operator uint 
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Form 1 


Form 9 


operator = 
TMenu& operator =(const TMenu& original); 
Returns the TMenu object. 


See also TMenu::operator uint 


operator uint() 

operator uint(); 

Returns the menu's handle. This function provides compatibility with functions that 
require a uint menu parameter. 


Seealso ‘’Menu::operator HMenu 


RemovelMenu 
boo] RemoveMenu(uint item, uint flags); 
Removes the menu item from the menu but does not delete it if it is a submenu. 


See also —TMenu::DeleteMenu 


SetMenultemBitmaps 
bool SetMenultemBitmaps(uint item, uint flags, const TBitmap* bmpUnchecked=0, 

const TBitmap* bmpChecked=0); 
Specifies the bitmap to be displayed when the menu item is checked and unchecked. 
item indicates the menu item to be associated with the bitmap. flags indicates how the 
size parameter is interpreted (whether by MF_BYPOSITION or by 
MF_BYCOMMAND). GetMenuCheckMarkDimensions gets the size of the bitmap. 


Seealso Menu::GetMenuCheckmarkDimensions, TBitmap 


Protected data members 


Handle 
HMENU Handle; 
Holds the handle to the menu. 


ShouldDelete 
bool ShouldDelete; 
ShouldDelete is set to true if the destructor needs to delete the handle to the menu. 


Seealso TMenu::DeleteMenu, TMenu::RemoveMenu 


Protected member functions 


DeepCopy 

static void DeepCopy(TMenu& dest, const TMenu& source, int offset = 0, int count = —1); | 
Makes a deep copy (that is, an actual copy of the menu, not just a copy of pointers or 
handles to a menu) of the menu. This form of DeepCopy copies count number of pop-up 
menus or menu items from src beginning at offset and appends the items or menus to the 
destination menu. If count is passed as —1, all source menu items are copied. 


static void DeepCopy(TMenué dst, int dstOff, const TMenué src, int srcOff = 0, int count = —1); 
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Makes a deep copy (that is, an actual copy of the menu, not just a copy of pointers or 
handles to a menu) of the menu. This form of DeepCopy copies count number of pop-up 
menus or menu items from source beginning at offset and inserts the items or menus at 
the dstOffset position specified in the destination menu (dest). If count is passed as —1, all 
source menu items are copied. 


TMenuDescr class menu.h 


Derived from TMenu, TMenuDescr describes your menu bar and its functional groups. 
TMenuDescr provides an easy way for you to group menus on your menu bar and to 
add new groups to an existing menu bar. It uses a resource ID to identify the menu 
resource and an array of count values to indicate the number of pop-up menus in each 
group on the menu bar. | 


The TGroup enum enumerates the six basic functional groups on a menu bar: File, Edit, 
Container, Object, Window, and Help. TMenuDescr's constructors simply initialize the 
members based on the arguments passed: TFrameWindow's MergeMenu function 
actually performs the real work of merging the menu groups. 


One method you can use to create a menu involves invoking the TMenuDescr 
constructor and passing the number of group counts for each menu selection. 


For example, if your original menu looked like this: 


Edit Search Page Paragraph Word 


you might use the following group counts: 


‘FileGroup ic File 

EditGroup 2 Edit Search 
ContainerGroup = 1 View 

ObjectGroup 3 Page Paragraph Word 
WindowGroup 1 Window 

HelpGroup 1 Help 


You would then invoke the constructor this way: 
TMenuDescr (IDM _MYMENU, 1,2, 1, 3, 1, 1) 


You can build the previous menu by merging two menus. Set your application's frame 
menu bar this way: 


Hind | sil | ised Bal 


TMenuDescr (IDM FRAME, 1, 0, 1, 0, 1, 1) 
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and the word-processor child menu bar this way: 


/ Edit Search ; Page Paragraph Word | Help | 


TMenuDescr (IDM WPROC, 0, 2, 0, 3, 0, 1) 


If no child is active, only the frame menu will be active. When the word processor's child 
window becomes active, the child menu bar is merged with the frame menu. Every 
group that is 0 in the child menu bar leaves the parent's group intact. The previous 
example interleaves every group except for the last group, the Help group, in which the 
child replaces the frame menu. 


By convention, the even groups (File, Container, Window) usually belong to the outside 
frame or container, and the odd groups (Edit, Object, Help) belong to the child or 
contained group. 


If a—1 is used in a group count, the merger eliminates the parent's group without 
replacing it. For example, another child menu bar, such as a calculator, could be added 
to your application in this way. 


[ee [i 


 ‘TMenuDescr (IDM_WCALC, 0, 1, -1, 1, 0, 1) 


This produces a merged menu (with the View menu selection eliminated as a result of 
the —-1) that looks like this: 


[a [| Wo 


You could add a paint window in this way: 


| Ecit | Bitmap Pixel 


TMenuDescr (IDM WPAINT, 0, 1, 0, Dae Oe 4) 


This produces the following merged menu: 


| Fie || Edit View Bitmap Pixel Window Help 


The simplest way to add groups to a menu bar involves defining the menu groups and 
adding separators in a resource file. Insert the term MENUITEM SEPARATOR between 
each menu group and an additional separator if one of the menu groups is not present. 
For example, the resource file for Step14 of the ObjectWindows tutorial defines the 
following menu groups and separators: | 


IDM_MDICMNDS MENU 

{ 

// Display a grayed File menu 

MENUITEM "File", 0,GRAYED ;placeholder for File menu from DocManager 
MENUITEM SEPARATOR 

MENUITEM "Edit", CM_NOEDIT ;placeholder for Edit menu from View 
MENUITEM SEPARATOR . 
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MENUITEM SEPARATOR 
MENUITEM SEPARATOR 
POPUP "&Window" 

{ 


// Options within the Window menu group 


MENUITEM "&Cascade", CM_CASCADECHILDREN 
MENUITEM "&Tile", CM_TILECHILDREN 
MENUITEM "Arrange &Icons", CM_ARRANGEICONS 
MENUITEM "C&lose All", CM_CLOSECHILDREN 
MENUITEM "Add &View", CM_VIEWCREATE 


} 
MENUITEM SEPARATOR 
POPUP "&Help" 


{ 
MENUITEM "&About", | CM_ABOUT 


} 
} 


(You can see the separators by loading Step14.rc into Resource Workshop and disabling 
the View as Popup Option in the View menu. 


This resource file defines an Edit group, a File group, a Window group, and a Help 
group, but no entries for Container or Object groups. 


Then, step14.cpp uses these commands from the resource file to set the main window 
and its menu, passing IDM_MDICMNDS as the parmeter to SetMenuDescr function, 
thus 


SetMainWindow (frame) ; | 
GetMainWindow( ) ->SetMenuDescr (TMenuDescr (IDM_MDICMNDS) ) ; 


and produces the following menu groups: 


[ea] wr [oe 


TMenuDescr's functions let you perform OLE2-like menu merging. That is, you can 
merge menus from a container's document (the MDI frame window) with those of an 
embedded object (the MDI child window). When the embedded object is activated in- 
place by double-clicking the mouse, the menu of the child window merges with that of 
the frame window. 


Public constructors and destructor 


Constructors 

TMenuDescr(); 

Default constructor for a TMenuDescr object. No menu resources or groups are 
specified. Constructs an empty menu bar. 


TMenuDescr(TResld id, int fg, int eg, int cg, int og, int wg, int hg, TModule* module = ::Module); 

Constructs a menu descriptor from the resource indicated by the id. and module 
parameters. Places the pop-up menus in groups according the values of the fg, eg, cg, of, 
wg, and hg parameters. The fg, eg, cg, of, wg, and hg parameters represent the functional 
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Form 3 


Form 4 


Form 5 


groups sadenuned by t the TGroup enum. Calls the function ExtractGroups to extract the 
group counts based on the separator items in the menu bar. 


TMenuDescr(const TMenuDescr& original); | 
Copies the menu descriptor object specified in the original parameter. 


TMenuDescr(TResld id, TModule* module = ::Module); 

Creates a menu descriptor from the menu resource specified in the id parameter. Calls © 
the function ExtractGroups to extract the group counts based on the separator items in 
the menu bar. 


TMenuDeser(HMENU hMenu, int fg, int eg, int cg, int og, int wg, int hg, TModule* rnoadier: = ::Module); 
Constructs a menu descriptor from the menu handle indicated in the hMenu parameter. 
The menu descriptor can have zero or more pop-up menus in more than one functional 
group. The fg, eg, cg, of, wg, and hg parameters represent the functional groups identified 
by the TGroup enum. Calls the function ExtractGroups to extract the group counts based 
on the separator items in the menu bar or uses the group count parameters specified if 
there are no separators in the menubar. 


Destructor 
~TMenuDescr(); | 
Destroys the TMenuDescr object. 


Type definitions 


TGroup enum 

enum TGroup{FileGroup, EditGroup, ContainerGroup, ObjectGroup, WindowGroup, HelpGroup, NumGroups}; 
Used by TMenuDescr, the TGroup enum describes the following constants that define the 
index of the entry in the GroupCount array. | 


FileGroup Index of the File menu group count 
EditGroup Index of the Edit menu group count 
ContainerGroup Index of the Container menu group count 
ObjectGroup Index of the Object group count 
WindowGroup Index of the Window menu group count 
HelpGroup Index of the Help menu group count 
NumGroups Total number of groups | 


Seealso ‘TMenuDescr::GroupCount 


Public member functions 


GetHandle 
HMENU GetHandle() const; 
Gets the handle to the menu, possibly causing any deferred menu acquisition to occur. 
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GetModule 
TModule* GetModule() const; 
Returns a pointer to the module object. 


SetModule 
void SetModule(TModule* module); 
Sets the default module object for this menu descriptor. 


Getld 
TResid Getld() const; 
Gets the menu resource ID used to construct the menu descriptor. 


GetGroupCount 

int GetGroupCount(int group) const; 

Gets the number of menus in a specified group within the menu bar. There are a 
maximum of six functional groups as defined by the TGroup enum. These groups 
include FileGroup, EditGroup, ContainerGroup, ObjectGroup, WindowGroup, and 
HelpGroup. | 


Seealso Group enum 


ClearServerGroupCount 

void ClearServerGroupCount();; 

Clears the odd groups (that is, 1, 3, 5 or Edit Group, Object Group, and Help Group) in 
the menu bar for a server application. 


Seealso Group enum, TOcMenuDescr 


ClearContainerGroupCount 

void ClearContainerGroupCount(); 

Clears the even groups (that is, 0, 2, 4 or File Group, Container Group, Window Group) 
in the menu bar for a container application. 


Seealso [Group enum, TOcMenuDescr 
Merge 


bool Merge(const TMenuDescr& sourceMenuDescr); 
Merges the functional groups of another menu descriptor into this menu descriptor. 


bool Merge(const TMenuDescr& sourceMenuDescr, TMenu& destMenu); 
Merges the functional groups of this menu descriptor and another menu descriptor into 
an empty menu. | 


Seealso TMenuDesc::TGroup enum 


Protected data members 


Id 

TResld Id; 

Resource ID for the menu. The resource ID is passed in the constructors to identify the 
menu resource. 3 
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GroupCount 
— int GroupCount{NumGroups]; 


An array of values indicating the number of pop-up menus in each group on the menu 
bar. 


Seealso TGroup enum 


Module 
TModule* Module 
Points to the TModule object that owns this TMenuDescr. 


Protected member functions 


ExtractGroups 

_ bool ExtractGroups(); 
Extracts the group counts from the loaded menu bar by counting the number of menus 
between separator items. After the group counts are extracted, the separators are 
removed. 


See also TMenu, TOcMenuDescr 


TMenultemEnabler class rae ——framewin.h 


Derived from TCommandEnabler, TMenultemEnabler is a command enabler for menu 
items. The functions in this class modify the text, check state, and appearance of a menu 
item. | 


Public constructor 


Constructor 

TMenultemEnabler(HMENU hMenu, uint id, HWND hWndReceiver, int position); 

Constructs a TMenultemEnabler with the specified command ID, for the menu item, 
message responder (hWndReceiver), and position on the menu. 


Protected data member 


HMenu 
HMENU HMenu; 
The menu that holds the item being enabled or disabled. 


Position 
int Position; 
The postion of the menu item. 
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Public member functions 


Enable 

void Enable(bool enable); 

Overrides TCommandEnable::Enable. Enables or disables the menu options that control 
the appearance of the corresponding menu item. 


GetMenu 
HMENU GetMenu(); 
Returns the menu that holds the item being enabled or disabled. 


GetPosition 
int GetPosition(); 
Returns the position of the menu item. 


SetText 
void SetText(LPCSTR); 
Overrides TCommandEnable::SetText, Changes the text of the corresponding menu item. 


SetCheck 
void SetCheck(int state): 

- Overrides TCommandEnable::SetCheck. Checks or unchecks the corresponding menu 
item. The state parameter reflects the menu item's state, which can be checked, 
unchecked, or indeterminate. 


- TMessageBar class | messageb.h 


Derived from TGadgetWindow, TMessageBar implements a message bar with one text 
gadget as wide as the window and no border. Normally positioned at the bottom of the 
window, the message bar uses the default gadget window font and draws a highlighted 
line at the top. 


Public constructor 


Constructor 

TMessageBar(TWindow* parent = 0, TFont* font = new TGadgetWindowFont, TModule* module = 0); 
Constructs a TMessageBar object with the gadget window font. Sets IDW_STATUSBAR, 
HighlightLine to true, and TTextGadget’s member WideAsPossible to true, making the text 
gadget as wide as the window. 


Seealso TGadgetWindowFont::TGadgetWindowFont 


Public member functions 


SetHintText 
virtual void SetHintText(const char* text); 
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Sets or clears the menu hint text for the message bar. Hint text is displayed over all other 
gadgets and is used for menu and control bar button help. 


SetText 
void SetText(const char* text); 7 
Forwards the message in the message bar to the text gadget for formatting. 


Seealso T’'TextGadget::SetText 


Protected data members 


HighlightLine 
bool HighlightLine; 
Is true if a highlighted line is drawn. 


HintText 


_ char* HintText; 
Stores the command hint text, if any, that's currently being displayed. 


Protected member functions 


GetDesiredSize 

void GetDesiredSize(TSize& rect); 

Calls TGadget Window's GetDesiredSize to get the size of the message bar. Then, if a 
highlighting line is drawn, adjusts the size of the message bar. 


Seealso TGadgetWindow::GetDesiredSize 
GetinnerRect 


void GetInnerRect(TRect& rect); 
GetInnerRect computes the rectangle inside the borders and nara of the message bar. 


Seealso TGadgetWindow::GetInnerRect 


PaintGadgets 

void PaintGadgets(TDC& dc, bool erase, TRect& rect); 

Adjusts the message bar and paints a highlight line. Then, PaintGadgets either paints the 
hint text if any is set or calls TGadgetWindow::PaintGadgets to repaint each Bares 


Seealso TGadgetWindow::PaintGadgets 


Derived from TDC, TMetaFileDC provides access to a device context with a metafile 
selected for drawing. 
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Public constructor and destructor 


Constructor 
TMetaFileDC(const char far* filename = 0); 
Creates a TMetaFileDC object with the data written to the named file if one is provided. 


Destructor 
~TMetaFileDC(); 
Destroys this object. 


Seealso TDC::TDC 


Public member function 


Close 

HMETAFILE Close(); 

Closes this metafile DC object. Sets the Handle data member to 0 and returns a pointer to 
anew T'MetaFilePict object. 


Seealso TMetaFilePict 


Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


~ Formé6 


TMetaFilePict is a support class used with TMetaFileDC to simplify metafile operations, 
such as playing into a DC or storing data on the clipboard. TMetaFilePict automatically 
handles the conversion between a metafile and a metafilepict. 


Public constructors and destructor 


Constructors 
TMetaFilePict(HMETAFILE handle, TAutoDelete autoDelete); 
Creates a TMetaFilePict object using the given handle argument. 


TMetaFilePict(const TClipboard& clipboard); 
Creates a TMetaFilePict object from the contents of the specified clipboard. 


TMetaFilePict(const char* filename); 
Creates a TMetaFilePict object for the metafile stored in the named file. 


TMetaFilePict(uint size, void far* data); 
Creates a TMetaFilePict object for the memory-based metafile specified by data. The data 
buffer must hold a metafile of length size bytes. 


TMetaFilePict(HGLOBAL data); 
Creates a TMetaFilePict object for the memory-based metafile specified by data.The data 
global memory block must hold a metafile. 


TMetaFilePict(const TMetaFilePict& orig, const char far* fileName = 0); 
Copies the metafile, orig, to the named file. If filename is 0 (the default), the metafile is 
copied to a memory-based metafile. 
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Destructor 
~TMetaFilePict() | 
Destroys this object. 


Seealso TClipboard 


Public member functions 


CalcPlaySize 
TSize CalcPlaySize(TDC& dc, const TSize& defSize) const; 
Calculates the size of this metafile when played on a given DC. 


Seealso TDC, TSize © 


GetMetaFileBits 

HANDLE GetMetaFileBits(): 

Returns a handle to a global memory block containing this metafile as a collection of 
bits. The memory block can be used to determine the size of the metafile or to save the 
metafile as a file. 


GetMetaFileBitsEx 

uint32 GetMetaFileBitsEx(uint size, void* data); 
32-bit only. Retrieves the contents of the metafile associated with this object and copies 
them (up to size bytes) to the data buffer. If data is nonzero and the call succeeds, the | 
actual number of bytes copied is returned. If data is 0, a successful call returns the 
number of bytes required by the buffer. A return value of 0 always indicates a failure. 


Height 
int Height() const; 
Retrieves the height of this metafile. 


operator << 

TClipboard& operator <<(TClipboard& clipboard, TMetaFilePict& mfp); 

Places the TMetaFilePict object onto the Clipboard. Returns a reference to the poe 
Clipboard, allowing the usual chaining of << operations. 


Seealso TClipboard 


MappingMode 
unsigned MappingMode()const; 
Retrieves the mapping mode of this metafile. 


operator HMETAFILE() 
operator HMETAFILE() const; 
Type-conversion operator. 


PlayOnto 
bool PlayOnto(TDC& dc, const TSize& defSize) const; 
Plays the metafile into a DC. 


See also TDC, TSize 


302 ObjectWindows Reference Guide 


TModule class 


SetMappingMode 
void SetMappingMode(unsigned mm); 
Sets the mapping mode of this metafile. 


SetSize 
void SetSize(const TSize& size); 
Sets the size of this metafile. 


Size 
TSize Size() const; 
Retrieves the size of this metafile. 


ToClipboard 

void ToClipboard(TClipboard& clipboard, unsigned mapMode = MM_ANISOTROPIC, const TSize& 
extent=TSize(0,0)); 

Puts this metafile onto the Clipboard. 


Seealso TClipboard, TSize 


Width 
int Width() const; 
Retrieves the width of this metafile. 


Protected data members 


Extent 
TSize Extent; 
Holds the extent or size of the metafile. 


Mm 
int Mm; 
Stores the mapping mode for the metafile. 


TModule class module.h 


Form 1 


ObjectWindows dynamic-link libraries (DLLs) construct an instance of TModule, which 
acts as an object-oriented stand-in for the library (DLL) module. TModule defines 
behavior shared by both library and application modules. ObjectWindows applications 
construct an instance of T’Application, derived from TModule. TModule's constructors 
manage loading and freeing of external DLLs, and the member functions provide 
support for default error handling. 


Public constructors and destructor 


Constructors ‘ 

TModule(const char far* name, HINSTANCE hinstance, const char far* cmdLine); 

Constructs a TModule object for an ObjectWindows DLL or program from within 
LibMain or WinMain. Calls InitModule to initialize hInstance and cmdLine. 
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. Form3 


_ TModule(const char far* name, HINSTANCE hinstance); 
Constructs a TModule object that is an alias for an already loaded DLL or program with 
an available HInstance. When the TModule is destructed, the instance i isn't euomateasy 


freed. name, which is optional, can be 0. 


TModule(const char far* name, bool shouldLoad = true); 


Constructs a [Module object that is used as an alias for a DLL. If shouldLoad is true, 
TModule will automatically load and free the DLL. If shouldLoad is false, then the 
HInstance needs to be set later using InitModule. 


Destructor 
virtual ~TModule(); 
Destroys a TModule object and deletes IpCmdLine. 


Public data members 


IpCmdLine 

char far* IpCmdLine; | 

A null-terminated string, [pCmdLine points to. a copy of the command-line arguments 
passed when the module is loaded. Notice that lpCmdLine is different from the WIN32 
[pCmdLine in which the full path name of the module is appended to the command-line _ 
arguments. Whether running under WIN16 or WIN32, ObjectWindows 
TModule::lpCmdLine data member includes only the command-line arguments. Note 
that the run-time library global variables _argv*[] and _arge contain identical 
information for both WIN16 and WIN32 APIs, and that _argv[0] points to the full path 
name of the module. 


Seealso TApplication 


Module 
extern TModule *Module; 
Holds a global pointer to the current module. 


Seealso Application 


— Status 


TStatus Status; 

Status contains the module status and is included for backward compatibility with 
ObjectWindows 1.0 applications. ObjectWindows 2.0 instead uses exceptions to handle 
errors. Setting Status to any nonzero value will throw a TXCompatibility exception. 


See also TXCompatibility::MapStatusCodeToString 


— Public member functions 


AccessResource 

int AccessResource(HRSRC hRsrc) const; | 

Used for 16-bit applications, AccessResource finds the specified resource. The preferred 
method i is to use FindResource. | | 


| See also TModule::FindResource 
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AllocResource 

HGLOBAL AllocResource(HRSRC hRsrc, uint32 size) const; 

Used for 16-bit applications, AllocResource loads a resource into memory. The preferred 
method is to use LoadResource. 


Seealso TModule::LoadResource 


CopyCursor 

HCURSOR CopyCursor(HCURSOR hCursor) const; 

Used for 16-bit applications, CopyCursor copies the cursor specified in hCursor. The 
return value is a handle to the duplicate cursor. 


Seealso TIcon 


Copylcon 

HICON Copylcon(HICON hicon) const; 

Copies the icon specified in hIcon. The return value is a handle to the icon or 0 if 
unsuccessful. When no longer required, the duplicate icon should be destroyed. 


Error 

virtual void Error(int errorCode); 

Processes errors identified by the error value supplied in errorCode. Error displays the 
error code in a message box and asks the user if it is OK to continue. If the user does 
continue, the program might or might not be able to recover. If the user does not 
continue, the program terminates. Error can be overridden with another kind of 
exception handler. This function is included only for backward compatibility with 
ObjectWindows 1.0. If you are writing ObjectWindows 2.0 applications, use the 
following Error function instead. 


virtual int Error(xmsg& x, unsigned captionResld, unsigned promptResId=0); 

Called when fatal exceptions occur, Error takes an xmsg exception object, a resource ID 
for a message box caption, and an optional resource ID for a user prompt. By default, 
Error calls HandleGlobalException with the xmsg object and the strings obtained from the 
resources. An application (derived from TApplication which is derived from TModule) 
can reimplement this function to provide alternative behavior. 


A nonzero status code is returned to indicate that an error condition is to be propagated; 
a zero status indicates that the condition has been handled and that it is OK to proceed. 
ObjectWindows uses this status code inside its message loop to allow the program to 
resume. The global error handler (defined in except.h), which displays the message text, 
is 

int _OWLFUNC HandleGlobalException(xmsg& x, char* caption, char* canResume) ; 


ExecDialog 

int ExecDialog(TDialog* dialog); 

Executes a dialog box. This function is included only for backward compatibility. Use 
TDialog::Execute instead. 


FindResource 

HRSRC FindResource(TResld id, const char far* type) const; 

Finds the resource indicated by id and type and, if successful, returns a handle to the 
specified resource. If the resource cannot be found, the return value is zero. The id and 
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type parameters either point to zero-terminated strings or specify an integer value. type 
~ can be one of the standard resource types defined below. | 


RT_ACCELERATOR Accelerator table 


RT_BITMAP — Bitmap 

RT CURSOR _ Cursor 

RT_DIALOG Dialog box 
RT_FONT > | Font 

RT_FONTDIR - Font directory 
RTICON | Icon 

RT_ MENU Menu 

RT _RCDATA User-defined resource 
RT_STRING String 


Seealso TResID 


GetClientHandle 

HWND GetClientHandle(HWND hWnd); 

Gets the handle to the client window. This function is included only for backward 
compatibility with ObjectWindows 1.0. 


GetClassinfo 

—_ bool GetClassInfo(const char far* name, WNDCLASS far* wndclass) const; 
Used particularly for subclassing, GetClassInfo gets information about the window class 
specified in wndclass. name points to a zero-terminated string that contains the name of 
the class. wndclass points to the WNDCLASS structure that receives information about 
the class. If successful, GetClassInfo returns nonzero. If a matching class cannot be found, 
GetClassInfo returns zero. 


See also VWNDCLASS struct 


Getinstance 
HINSTANCE Getlnstance() const; 
Returns the instance handle for this module. 


GetinstanceData 

int GetInstanceData(void* data, int len) const; 

Used only for 16-bit applications, GetInstanceData gets data from an sheniy running 
instance of an application. len is the size of the buffer. 


GetModuleFileName — 
int GetModuleFileName(char far* buff, int maxChars); 

- Returns the expanded file name (path and file name) of the file from which this module 
was loaded. buff points to a buffer that holds the path and file name. maxChars specifies 
the length of the buffer. The expanded file name is truncated if it exceeds this limit. 
GetModeFileName returns 0 if an error occurs. 
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GetModuleUsage 

int GetModuleUsage() const; 

Used only for 16-bit applications, GetModuleUsage returns the reference count of the 
module, if successful. The reference count is incremented by one each time a module is 
loaded, and decremented by one each time a module is freed. 


GetName 
const char far* GetName() const; 
Gets the name of the module. 


Seealso ::GetName (Windows API) 


GetParentObject 

TWindow* GetParentObject(HWND hWndParent); 

Gets a handle to the parent window. This function is included only for backward 
compatibility with ObjectWindows 1.0. 


Seealso ::GetParentObject (Windows API) 


GetProcAddress 

FARPROC GetProcAddress(const char far* fenName) const; 

Returns the entry-point address of the exported function fcnName if the function is 
found. Returns NULL otherwise. 


InitModule 

void InitModule(HINSTANCE hinstance, const char far* cmdLine); 

Performs any instance initialization necessary for the module. If the module cannot be 
created, a TXInvalidModule exception is thrown. 


IsLoaded 

bool IsLoaded() const; 

Returns a nonzero value if the instance handle is loaded. Use this function primarily to 
ensure that a given instance is loaded. 


LoadAccelerators 

HACCEL LoadAccelerators(TResld id) const; 

Loads the accelerator table resource specified by id. LoadAccelerators loads the table only 
if it has not been previously loaded. If the table has already been loaded, LoadAccelerators 
returns a handle to the loaded table. 


LoadBitmap - 

HBITMAP LoadBitmap(TResld id) const; | 

Loads the bitmap resource specified by id. If the bitmap cannot be found, LoadBitmap 
returns 0. 


Seealso T’BitMap, TResID, ::LoadBitmap (Windows API), OBM_XXXX values 
(Windows API) | 


LoadCursor 
HCURSOR LoadCursor(TResld id) const 
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Loads the cursor resource specified by id into memory and returns a handle to the 


Form 1 


Form 2 


cursor resource. If the cursor resource cannot be found or identifies a resource that is not 
a cursor, LoadCursor returns 0. 


Seealso TCursor, TResID, “LoadCursor (Windows API) 


Loadicon 

HICON LoadIicon(const char far* name) const; - 

Loads the icon resource indicated by the parameter, name, into memory. LoadIcon (eade 
the icon only if it has not been previously loaded. If the icon resource cannot be found, 
LoadIcon returns 0. | 


LoadIcon can be used to load a predefined Windows icon if name points to one of the 
Windows IDI_XXXX values. 


—Seealso Tlcon, ::LoadIcon (Windows API), IDI_XXXX values (Windows API) 


LoadMenu 

HMENU LoadMenu(TResld id) const; 

Loads the menu resource indicated by id into memory. If the menu resource cannot be 
found, LoadMenu returns 0. 


See also TMenu, ::LoadMenu (Windows API) 


LoadResource 

HGLOBAL LoadResource(HRSRC hRsrc) const; 

Loads a resource indicated by hRsrc into memory and returns a handle to the memory 
block that contains the resource. If the resource cannot be found, the return value is 0. 
The hRsrc parameter must be a handle created by FindResource. 


LoadResource loads the resource into memory only if it has not been previously loaded. If 
the resource has already been loaded, LoadResource increments the reference count by 
one and returns a handle to the existing resource. The resource remains loaded until it is 
discarded. 


LoadString 

int LoadString(uint id, char far* buff, int maxChars) const; 

Loads a string resource identified by id into the buffer pointed to by buff. maxChars 
indicates the size of the buffer to which the zero-terminated string is copied. A string 
longer than the length specified in maxChars is truncated. The return value is the 
number of characters copied into the buffer, or 0 if the string resource does not exist. 


string LoadString(uint id) const; 
Loads a string resource identified by id 


LowMemory 
bool LowMemory(); 
This function, which is obsolete, always returns 0. 


MakeWindow 
TWindow* MakeWindow(TWindow* win); 
This function is obsolete. Use the TWindow::Create function aeabeaal 
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operator HINSTANCE() 

operator HINSTANCE() const; 

Returns the handle of the application or DLL module represented by this TModule. The 
handle must be supplied as a parameter to Windows when loading resources. 


operator == 
bool operator ==(const TModule& other) const; 
Returns true if this instance is equal to the other instance; otherwise, returns false. 


RestoreMemory 
void RestoreMemory(); 
This function, which is obsolete, restores memory. 


Setinstance 

void SetInstance(HINSTANCE hinstance); 

Sets the instance handle for this TModule. SetInstance is used for special cases in which 
the Instance is not known when the module is constructed. 


SetName 
void SetName(const char far* name); 
Accessor function that sets the name of the module. 


SetResourceHandler 

const RSRCHDLRPROC SetResourceHandler(const char far* type, RSRCHDLRPROC loadProc) const; 
Used for 16-bit applications, SetResourceHandler installs a callback function that loads 
resources. type points to a resource type. loadProc is the address of the callback 
procedure. If successful, SetResourceHandler returns a pointer to a previously installed 
resource handler. If no resource handler has been installed, SetResourceHandler returns a 
pointer to the default handler. This function is useful for handling user-defined resource 


types. 


SizeofResource 

uint32 SizeofResource(HRSRC hRsrc) const; 

Returns the size, in bytes, of the resource indicated by hRscr. The resource must be a 
resource handle created by FindResource. If the resource cannot be found, the return 
value is 0. | 


Because of alignment in the executable file, the returned size might be larger than the 
actual size of the resource. An application cannot rely on SizeofResource for the exact size 
of a resource. 


ValidWindow 
TWindow* ValidWindow(TWindow* win); 
This function, which is obsolete, returns a handle to the valid window. 


Protected data members 


Hinstance | 
- HINSTANCE Hinstance; 
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-TXInvalidModule class 


Contains the executing instance of either the application or DLL module. The instance 


must be supplied as a parameter to Windows when loading resources. 


Name 


_ int GetModuleFileName(char far* buff, int maxChars): 


Returns the expanded file name (path and file name) of the file from which this module 
was loaded. buff points to a buffer that holds the path and file name. maxChars specities 
the length of the buffer. The expanded file name is truncated if it exceeds this limit. 
GetModeFileName returns 0 if an error occurs. 


TModule::TXinvalidModule class ‘module.h 


- Anested class, TXInvalidModule describes an exception that results from an invalid 


module. A window throws this exception if it can't create a valid TModule object. 


Public constructor 
Constructor 


TXInvalidModule(); 
Constructs a TXInvalidModule object. 


Public member functions 


Clone 


TXOw! Clone(): 
Copies the TXInvalidModule exception object. 


Throw 


void Throw(); 


Throws the T'XInvalidModule exception object. 


Derived from TClientDC, TOleClientDC is a helper class that translates between two 
different coordinate systems. For example, the window's logical points may be 
measured in HIMETRIC or twips whereas the actual ouput device's (the viewport) 
coordinates may be measured in pixels. Without the help of this class, you would need 
to create a client DC and then set up the window's logical coordinates (its origin) and its 
width and height (its extent) as well as the viewport's origin (measured in device 
coordinates) and extent. Instead, TOleClientDC performs these calculations for you by 
mapping logical points to device points and vice versa. 


TOleClientDC works with a TOleWindow object. By default, TOleClientDC kes care of 
both scaling (adjusting the extents of the window and the viewport) and scrolling 
(adjusting the origins of the window and the viewport). 
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Public constructor 


Constructor 

TOleClientDC(TOleWindowé win, bool scale = true); 

Constructs a TOleClientDC object . The parameter win references the window that 
TOleClientDC uses to create a DC. If the scale parameter is true, TOleClientDC takes care 
of scaling. However, if your application handles scaling, you can pass scale as false. 


Scrolling is controlled by the presence of a scroller (TScroller). TOleClientDC, by default, 
takes care of both scaling and scrolling. 


Seealso TClientDC, TOleWindow 


TOleDocument class oledoc.h 


Derived from TStorageDocument, TOleDocument implements the Document half of the 
Doc/View pair. That is, TOleDocument manages the document's data while the 
corresponding TOleView object determines how the data is displayed on the screen. 
Basically, TOleDocument is a TStorageDocument with a knowledge of TOcDocument 
through its pointer to TOcDocument. 


TOleDocument is responsible for creating compound documents (documents that can 
hold a variety of embedded objects from various source applications), closing 
documents, reading documents from storage (an area within a file where data is stored), 
and writing documents to storage. In the case of a server, the document consists of a 
single object. In the case of a container, the document can consist of one or more 
embedded objects (also referred to as parts). 


To accomplish these tasks, TOleDocument talks to the underlying ObjectComponents 
classes through the use of functions such as GetOcApp, GetOcDoc, and SetOcDoc. 


See also | 
TOleView, TStorageDocument, TOcDocument, TOcRemView 


Public constructor and destructor 


Constructor 
TOleDocument(TDocument* parent = 0); 
Constructs a TOleDocument object associated with the given parent TDocument object. 


Destructor 

~TOleDocument(); 

Destroys the TOleDocument object. In the case of an OLE container, the compound file 
remains open until all of the views shut down. 
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Public member functions 


CanClose 

virtual boo! CanClose(); 

Prepares the document for closing. Before closing the current document, checks to see if 
all child documents can be closed. If any child returns false, CanClose returns false and 
aborts the process. If all children return true, CanClose checks to see if the document has 
been changed. If so, it asks the user to save the document, discard any changes, or cancel 
the operation. If the document has not been changed, and all child documents return 
true, this CanClose function returns true, thus indicating that the document can be 
closed. 


CanClose also calls ReleaseDoc on its associated ObjectComponents document to make 
sure that all the embedded objects are closed properly. 


See also TOleDocument::ReleaseDoc 


Close 
bool Close(); 


Ensures that the [Storage is released properly and disconnects any active server in the 
document. A compound file must be closed before it is reopened. | 


Seealso T’'TOleDocument::Open 

Commit 

bool Commit(bool force); 

Commits the current document's data to storage. If force is true and the data is not dirty, 


all data is written to storage and Commit returns true. If force is false, the data is written 
only if it is dirty. 


The data has been changed since the last save operation. 


Seealso T’TOleDocument::Revert 
GetNewStorage 
virtual IStorage*GetNewStorage(); 


Typically used in a SaveAs menu selection, GetNewStorage gets a new storage for the 
document. 


If the document's path changes, for example, use this function to create a new storage. 


GetOcApp 
TOcApp* GetOcApp(); 
Returns the ObjectComponents application associated with this TOleDocument object. 


Seealso TOcApp 


GetOcDoc 
TOcDocument*GetOcDoc(); 
Returns the ObjectComponents document associated with this TOleDocument ore 


Seealso TOleDocument::SetOcDoc 
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InitDoc 

virtual bool InitDoc(); 

Overrides TDocument's InitDoc function and creates or opens a compound file so that 
there is an [Storage associated with this document's embedded objects. Uses a 
TOcDocument object to perform the the actual interaction with the OLE [Storage and 
Stream interfaces, which are ultimately responsible for establishing the relationship 
between a compound file and its storage. 


See also TOcDocument, TDocument::InitDoc 


Open 

bool Open(int mode, const char far* path); 

Loads the embedded objects, if any, using the path specified in path. mode is a 
combination of bits that specify how the embedded objects are opened (for example, 
read only, read/write, and so on). 


Seealso TTOleDocument::Close 


PathChanged 

bool PathChanged(); | 

Checks if the current document's path is the same as the TOcDocument's path. If the 
paths are not the same, PathChanged returns true. 


See also TOcDocument 


PreOpen 

virtual void PreOpen(); 

Before the document is actually opened, PreOpen gives the derived class a chance to 
perform a particular operation, for example, setting a different open mode for the 
compound document. 


See also dtxxxx document constants 


Read 

virtual bool Read(); | 
Loads the embedded objects from the compound file. A container should call this 
function when it wants to loads any embedded objects. 


See also TOleDocument::Write 


ReleaseDoc 

virtual bool ReleaseDoc(); 

Releases the ObjectComponents document when the server is finished using the 
document. | 


See also TOleDocument::CanClose 


Revert 
bool Revert (bool clear); 


Performs the reverse of Commit. Cancels any changes made to the document since the 
last time the document was saved to storage. 


See also TTOleDocument::Commit 
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SetOcDoc 
void SetOcDoc(TOcDocument* doc); | | 
Sets the ObjectComponents document associated with this TOleDocument object. 


See also TOleDocument::GetOcDoc 


SetStorage 
virtual bool SetStorage(IStorage* stg); 
Attaches the I Storage pointer (stg) to this document. If successful, SetStorage returns true. 


An OLE storage interface that ObjectComponents implements when it needs to assign 
storage to a document 


Write 

virtual bool Write(); 

Saves the embedded objects to the compound file. A container should call this function 
when it wants to save its embedded objects to storage. 


See also TOleDocument::Read 


_TOleFactoryBase<> class olefacto.h 


A template class, TOleFactoryBase<> creates callback code for ObjectWindows classes. 
_ The main purpose of the factory code is to provide a callback function, Create, that 
ObjectComponents calls to create objects. 


Just as a recipe consists of a list of instructions about how to make a particular kind of 

food, a template, such as TOleFactoryBase<>, contains instructions about how to make 

an object, in this case, a factory object. TOleFactoryBase<> includes two public member 
functions. The three additional functions are passed as template arguments. Although 
these template arguments actually belong to the class that is instantiated when you fill 
in the arguments to TOleFactoryBase<>, they are described here for convenience. 


Use TOleFactoryBase<> to manufacture objects in general, whether or not they are 
embedded, OLE- ae or use the Doc/View model. These objects might or might not 
be connected toOLE. — | 


The callouts are supplied through the arguments passed to the template class. The 
factory base class takes three template parameters: the application type, a set of 
functions to create the object, and a set of functions to create an automation object. 
Depending on the arguments passed, you can make the following OLE-enabled 
components: | 


© Doc/View components that are automated 

© Doc/View components that are not automated 
¢ Non-Doc/View components that are automated 

¢ Non-Doc/View components that are not automated 


ObjectWindows provides a standard implementation. for object creation and 
automation. Factory Template Classes gives an overview of these classes. 
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By using TOleFactoryBase<> to obtain an OLE interface for your application, you can 
make objects that are accessible to OLE. That is, TOleFactoryBase<> handles any 
relationships with [Unknown, a standard OLE interface. 


See also 
TComponentFactory typedef, TOcRegistrar class, TAutoFactory class 


Public member functions 


TComponentFactory 

operator TComponentFactory(); 

Converts the object into a pointer to the factory. ObjectComponents uses this pointer to 
create the object. 


Create 

static |Unknown* Create(|Unknown* outer, uint32 options, uint32 id); 

A TComponentFactory callback function that creates or destroys the application or creates 
objects. If an application object does not already exist, Create creates a new one. The outer 
argument points to the OLE2 [Unknown interface with which this object aggregates 
itself. If outer is 0, If outer is 0, the object will become an independent object. 


The options argument indicates the application's mode while it is running. The values for 
options are either set from the command line or set by ObjectComponents. They are 
passed in by the Registrar to this callback. The application looks at these flags in order to 
know how to operate, and the factory callback looks at them in order to know what to 
do. For example, a value of amExeMode indicates that the server is running as an .EXE 
either because it was built as an .EXE or because it is a .DLL that was launched by an 
.EXE stub and is now running as an executable program. The TOcAppMode enum 
description shows the possible values for the options argument. 


If the application already exists and the object ID (id) equals 0, Create returns the 
application's OLE interface. Otherwise, it calls OCInit to create anew TOcApp and 
register the options from TOcAppMode enum, which contains OLE-related flags used in 
the application's command line. (These flags tell the application whether it has been run 
as a server, whether it needs to register itself, and so on.) If a component ID was passed, 
that becomes the component; otherwise, Create runs the application itself based on the 
values of the TOcAppMode enum and returns the OLE interface. 


Seealso TOleFactoryBase::DestroyApp, TOcAppMode enum 


Template arguments 


CreateApp 

static T* CreateApp(options); 

Creates a new application. By default, it creates a new application of template type T 
with no arguments. This is a static function that you can override in your application. 


The options are those passed to the factory. They can be one of the TOcAppMode enum 
values (for example, amRun, amEmbedding, and so on) that indicate the application's 
mode when running and indicate the options to the factory. 
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See also TOleFactoryBase::DestroyApp 


CreateObject 

static [Unknown* CreateObject(TApplication* app, TDocTemplate* tl [Unknown* outer); 

Creates an object using the document template referred to in tpl and the application 
specified in app. The outer parameter refers to the controlling [Unknown interface of the 
object with which this object is going to be aggregated. If outer is 0, the object is an 
independent object. 


You can override this static function to create your own object at run time. 
Seealso TOleFactoryBase: ia 


TOcView class 


DestroyApp 
static void DestroyApp(T* app); 
Destroys the application (app) by unregistering the object and deleting it. 


Seealso TOleFactoryBase::CreateApp 


TOleFrame class oleframe.h 


Derived from TDecoratedFrame, TOleFrame provides user-interface support for the main 
window of a single Document Interface (SDI) OLE application. Because it inherits 
TDecoratedFrame's functionality, TOleFrame is able to position decorations, such as 
toolbars, around the client window. Because of its OLE frame functionality, you will 
always want to create a TOleFrame as a main frame. For example, TOleFrame supports 
basic container operations, such as 


e Creating space in a container's frame window that the server has requested 
e Merging the container's menu and the server's menu 
e Processing accelerators and other messages from the server's message queue 


In addition to supporting the customary frame window operations and event-handling, 
TOleFrame provides functionality that supports OLE 2 menu merging for pop-up 
menus. 


Through the use of the EvOcXxxx event-handling member functions, TOleFrame 
responds to ObjectComponents messages sent to both the server and the container 
applications. Although most of the messages and functions provide container support, 
one message, EvOcAppShutDown, is server related, and one function, 

— GetRemViewBucket, supplies server support. Whether TOleFrame functions as a 
container or a server, it always has a pointer to a corresponding TOcApp. 


See also 
TOcApp, TDecoratedFrame 
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Public constructor and destructor 


Constructor 

TOleFrame(const char far* title, TWindow* clientWnd, bool trackMenuSelection = false, TModule* module = 0); 
Constructs a TOleFrame object with the specified caption for the frame window (title), 
the client window (clientWnd), and module instance. The trackMenuSelection parameter 
indicates whether or not the frame window should track menu selections (that is, 
display hint text in the status bar of the window when a menu item is highlighted). 


Destructor 
~TOleFrame(); 
Destroys a TOleFrame object. 


Public member functions 


AddUserFormatName 

void AddUserFormatName(char far* name, char far* resultName, char far* id); 

Adds user defined formats and the corresponding names to the list of Clipboard 
formats. Use this function if you want to associate a clipboard data format (name) with 
the description of the data format as it appears to users in the Help text of the Paste 
Special dialog box (resultName). To use a standard Clipboard format, set the id 
parameter to an appropriate constant (for example, CF_TEXT). Otherwise, if the format 
is identified by a string, pass the string as the name and omit the ID. 


See also TOcApp::AddUserFormatName 


GetOcApp 
TOcApp* GetOcApp(); 
Gets the ObjectComponents application associated with this frame window. 


See also TOcApp, TOleFrame::SetOcApp 


GetRemViewBucket 

TWindow* GetRemViewBucket(); 

Returns a pointer to the OLE frame's hidden helper window that holds all inactive 
server windows. It can also hold in-place tool bars and TOleView windows. 


SetOcApp 

void SetOcApp(TOcApp* app); | 

Sets the ObjectComponents application associated with this frame window to the 
applications specified in the app parameter. 


Seealso TOcApp, TOleFrame::GetOcApp 


Protected member functions 


CanClose 
bool CanClose(); 
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Returns true if the frame window can be closed. Tests to see if both the TOcApp and all 
child windows can close. If the application and all child windows return true, CanClose 
closes the frame window. 3 


See also TOcApp 


CleanupWindow 

void CleanupWindow(); | 

Performs normal window aeanae of any HWND-related resources. For DLL servers, 
CleanupWindow destroys the idle timer. 


~Seealso TWindow::CleanupWindow, TOleFrame::EvTimer 


Destroy | 

void Destroy(int retVal); | 
Checks with all the connected servers to ensure that they can close before destroying the 
frame window. If the user closes the application with objects still embedded, Destroy 
hides the frame window instead of destroying it. 


DestroyStashedPopups 

void DestroyStashedPopups(); 

Destroys the previously stored shared pop-up menus. Checks to see if StashCount is 0 
before destroying the menus. 


Seealso TOleFrame: pee eee Oe TOleFrame: StashCount 


EvActivateApp 

void EvActivateApp(bool active, HTASK hTask); 

Responds to a WM_ACTIVATEAPP message sent when a window is activated or 
deactivated. If active is true, the window is being activated. 


This message is sent to the top-level window being deactivated beter it is sent to the 
top-level window being activated. hTask is a handle to the current process. 


‘This event is forwarded to the TOcApp object, which activates an in-place server if one 
exists. 


Seealso TOcApp 


EvOcAppBorderSpaceReq 

bool EvOcAppBorderSpaceReq(T Rect far* rect); | 
Responds to an OC_APPBORDERSPACEREQ message sent to a container. The 
response is to ask the container if it can give border space in its frame window to the 
server. 


See also TOcApp::BorderSpaceSet 


EvOcAppBorderSpaceSet 

bool EvOcAppBorderSpaceSet(TRect far* rect); 

Responds to an OC_APPBORDERSPACESET message by making room in the 
container's frame window for the border space that the server has requested. 


See also TOcApp::BorderSpaceReq 
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EvOcAppDialogHelp 

void EvOcAppDialogHelp(TOcDialogHelp far& dh); 

Responds to an OC_APPDIALOGHELP message. The dh parameter refers to one of the 
TOcDialog Help enum constants that indicate the kind of dialog box the user has open. 
For example, dhBrowseLinks indicates that the Links dialog box is open. The 
TOcDialogHelp enum lists the help constants and their dialog box equivalents. 


See also TOcDialogHelp enum 


EvOcAppFrameRect 

bool EvOcAppFrameRect(TRect far* rect); 

Responds to an OC_APPFRAMERECT message sent to a container. The response is to 
get the coordinates of the client area rectangle of the application's main window. 


EvOcAppinsMenus 

bool EvOcAppinsMenus(TOcMenuDescr far& sharedMenu); 

Responds to an OC_APPINSMENUS message by merging the container's menu into the 
shared menu. The sharedMenu parameter refers to this merged menu. 


EvOcAppMenus 

bool EvOcAppMenus(TOcMenuDescr far& md); 

Responds to an OC_OCAPPMENUS sent to the container. The response is to install a 
merged menu bar. 


EvOcAppProcessMsg 

bool EvOcAppProcessMsg(MSG far* msg); 

Responds to an OC_APPROCESSMSG message sent to the container asking the server 
to process accelerators and other messages from the container's message queue. 


EvOcAppRestoreUl 

void EvOcAppRestoreUI(); 

Responds to an OC_APPRESTOREUI message by restoring the container's normal 
menu and borders because in-place editing has finished. 


EvOcAppShutdown 

bool EvOcAppShutdown(); 

Responds to an OC_APPSHUTDOWN message indicating that the last embedded 
object has been closed. The response is to shut down the server. 


EvOcAppStatus Text 

void EvOcAppStatusText(const char far*); 

Responds to an OC_APPSTATUSTEXT message by displaying text from the server on 
this container's status bar. 


EvOcEvent 

LRESULT EvOcEvent(WPARAM wParam, LPARAM |Param); 

Responds toa WM_OCEVENT message and subdispatches it to one of the EVOcXxxx, 
event-handling functions based on the value of wParam. WM_OCEVENT messages are 
sent by ObjectComponents when it needs to communicate with an OLE-generated 
event; for example, if a server wants to display toolbars. 
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EvSize | 
void EvSize(uint sizeType, TSize& size); 
Responds to an EV_WM_SIZE message indicating a change in the frame enon S size 
and forwards this information to the TOcApp, which then notifies any in-place server. 
The server uses this information to change the size of its tool bar, if necessary. 


-Seealso TOcApp::EvActivate 


EvTimer 

void EvTimer(uint timerld); 

If this is a .DLL server, EvTimer responds to a timer message by running an idle loop if 
the message queue is empty. | 


Seealso TOleFrame::CleanupWindow 


SetupWindow 

void SetupWindow(); 

Associates the ObjectComponents application with the window's HWND so that the 
TOcApp and the window can communicate. Prepares a place to insert the server's 
toolbars when in-place editing of the embedded object occurs. | 


Seealso TOcApp 


StashContainerPopups 

void StashContainerPopups(const TMenuDescr& shMenuDescr): 

Stores a local copy of the pop-up menus so they can be used for menu merging and then 
destroyed later by DestroyStashedPopups. shMenuDescr is the shared menu descriptor to 
be stored. Increments StashCount each time the pop-up menus are saved. | 


See also TOleFrame::DestroyStashedPopups, TMenuDescr 


Protected data members 


HoldMenu 
HMENU HoldMenu; 
Holds the handle to the container's previously saved copy of the menu. 


OcApp | 
TOcApp* OcApp; 
Points to the ObjectComponents application associated with this frame window. 


See also TOcApp 


StashCount 

int StashCount; 
Holds the number of menu bars that have been stored. This number indicates how 
many active in-place editing sessions you have open. 


See also StashContainerPopups, TOleFrame: DesteosSGaheaponups 


StashedContainerPopups 
TMenu StashedContainerPopups; 
Holds the stored, shared pop-up menus. 
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See also StashContainerPopups, TOleFrame::StashCount 


Response table entries 


-EV_WM SIZE Oo EvSize 
EV_WM_ACTIVATEAPP EvActivateApp 
EV_MESSAGE(WM_OCEVENT, EvOcEvent) = EvOcEvent 
EV_OC_APPINSMENUS EvOcAppInsMenus 
EV_OC_APPMENUS EvOcAppMenus 
EV_OC_APPROCESSMSG EvOcAppProcessMs¢ 
EV_OC_APPFRAMERECT EvOcAppFrameRect 
EV_OC_APPBORDERSPACEREQO EvOcAppBorderspaceReq 
EV_OC_APPBORDERSPACESET EvOcAppBorderSpaceSet 
EV_OC_APPSTATUSTEXT EvOcAppStatusText 
EV_OC_APPRESTOREUI EvOcAppkRestoreUI 
EV_OC_APPSHUTDOWN EvOcAppShutDown 
TOleMDIFrame class olemdifr.h 


Derived from TMDIFrame and TOleFrame, TOleMDIFrame provides OLE user-interface 
support for the main window of a Multiple Document Interface (MDI) application. 
TOleMD IFrame also talks directly to the ObjectComponents classes through the use of a 
pointer to the OcApp object. 


TOleMD IFrame inherits from TMD IFrame functionality that supports the use of MDI 
frame windows designed to serve as the main windows of an MDI-compliant 
application. From TOleFrame, TOleMDIFrame inherits decorated frame window 
functionality that supports the addition of decorations (such as toolbars and status lines) 
to the frame window. TOleMDIFrame also inherits the ability to 


¢ Create space that the server has requested in a container's frame window 

e Merge the container's menu into the server's menu 

e Process accelerators and other messages from the server's message queue 
¢ Support OLE 2 menu merging for pop-up menus | 


TOleMD IFrame also inherits from TOleFrame the ability to talk directly to the 
ObjectComponents classes through the use of a pointer to the OcApp object. 


See Step 14 of the ObjectWindows tutorial for an example of a program that uses 
TOleMD IFrame to create an OLE-enabled decorated MDI frame window. 


See also 
TMD IFrame, TDecoratedMDIFrame, TOleFrame, TOleFrame::SetOcApp 
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Public constructor and destructor 


Constructor 
TOleMDIFrame(const char far* title, TResldmenuReslid, TMDIClienté clientWnd = *new TMDIClient, 

bool trackMenuSelection = false, TModule*module = 0); 
Constructs a TOleMDIFrame object with the indicated title, menu resource ID, client 
window, and module instance. By default, because trackMenuSelection is false, menu 
hint text is not displayed. (These parameters coincide with those of TMDIFrame's 
constructor. ) 


Destructor 
~TOleMDIFrame(); 
Destroys the OLE MDI frame window object. 


See also TDecoratedMDIFrame 


Protected member functions 


DefWindowProc | 

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM IParam); 

Allows default processing for all messages except for a resizing message concerning the 
frame window, in which case, DefWindowProc returns nothing. 


EvActivateApp 

void EvActivateApp(bool active, HTASK hTask); 

Responds to a message indicating that the frame window of this application (hTask) is 
going to be either activated (active is true) or deactivated (active is false), and forwards 
this information to the TOcApp object. | 


\ 


See also TOcApp 


EvOcAppinsMenus 

bool EvOcAppInsMenus(TOcMenuDescr far*); 

Inserts menus into a provided menu bar, or merges them with a child window and 
servers. To do this, EvOcAppInsMenus creates a temporary composite menu for the 
frame and MDI child windows, then copies the shared menu widths to the 
ObjectComponents st structure. It saves the container popups so they can be destroyed 
later. 
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Response table entries 


EV_OC_APPINSMENUS — EvOcAppInsMenus 


TOleView class oleview.h 


Derived from TWindowView and TView, TOleView supports the View half of the Doc/ 
View pair and creates a window with a view that can display an associated document. 
Documents use views to display themselves to a user. Regardless of whether a view 
belongs to a server or a container, TOleView sets up a corresponding TOcDocument 
object (an entire compound document). 


In the case of an OLE-enabled container application, view refers to the window where 
the container application draws the compound document, which may consist of one or 
more linked and embedded objects. To display these objects in different formats, a 
container can be associated with more than one view. Similarly, to display the data 
properly, each embedded object can also have its own view. Each container view creates 
a corresponding ObjectComponents TOcView object. 


If the view belongs to an OLE-enabled server application, TOleView creates a remote 
view on the server's document (a TOcRemView object). TOleView takes care of 
transmitting messages from the server to the container, specifically in the case of 
merging menus and redrawing embedded objects. TOleView supports merging the 
server's and the container's pop-up menu items to form a composite menu. Because it 
knows the dimensions of the server's view, TOleView is responsible for telling the 
container how to redraw the embedded object. 


Similarly to TView, TOleView supports the creation of views and provides several event 
handling functions that allow the view to query, commit, and close views. TOleView 
also manages the writing to storage of documents that belong to a container or a server. 


See also 
TOcDocument, TOcView, TOcRemView, TOleWindow, TView 


Public constructor and destructor 


Constructor 

TOleView(TDocument& doc, TWindow* parent = 0); 

Constructs a TOleView object associated with the given document object (doc) and 
parent window (parent). , 


Destructor 
~TOleView(); 
Destroys the TOleView object and detaches the view from the associated document. 
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TOleView class _ 
Public member functions 


GetViewname | 
const char far* GetViewName(); 


Overrides TView's virtual Get ViewName function and returns the name of the class 
(TOleView). 


Seealso TView::GetViewName 


GetWindow 

TWindow* GetWindow(); 

Overrides TView's virtual GetWindow function and returns the TWindow instance 
associated with this view. 


See also TView::GetWindow 


SetDocTitle 

bool SetDocTitle(const char far* docname, int index); 

Overrides TView's and TWindow's virtual SetDocTitle function and stores the title of the 
document associated with this view. 


Seealso TView::SetdocTitle 


StaticName 

static const char far* StaticName(); 

Returns the constant string "OleView" that is displayed in the user interface selection 
box. | 


Seealso TListView::StaticName 


Protected member functions 


CanClose 

bool CanClose(); 

A view uses this function to verify whether or not it can shut down. If this is a server's 
view window , CanClose checks to see if any open-editing. is occurring on any of the 
embedded objects in the frame window. If so, CanClose closes this open-editing session _ 
by disconnecting the embedded object from its server. Then, hides the server's frame 
window and returns true when appropriate. If this is a container, CanClose queries all 
documents and views and returns true when all documents and views can be closed. 


Unlike in-place editing, which takes place in the container's window, open-editing 
occurs in the server's frame window. 


CreateOcView 

TOcView* CreateOCView(TDocTemplate* tpl, boo! isEmbedded, IUnknown* outer); 

Creates an ObjectComponents view associated with the embedded object. Associates 
the view with the document template specified in tpl. The isEmbedded parameter is true 
if the view is an embedded object. The outer parameter refers to the [Unknown interface 
with which the view will aggregate itself. 
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EvOcViewAttachWindow 

bool EvOcViewAttachWindow(bool attach); 

_ Attaches this view to its ObjectWindows parent window so the embedded object can be 
either opened and edited or deactivated. To attach a view to an embedded object, set the 
attach parameter to true. To detatch the embedded object, set the attach parameter to 
false. 


EvOcViewClose 

bool EvOcViewClose(); | | 

Asks the server to close the view associated with this document. Tests to see if the 
document has been changed since it was last saved. Returns true if the document and its 
associated view are closed. 


Seealso TOleView::EvOcViewSavePart 


EvOcViewlnsMenus 

bool EvOcViewInsMenus(TOcMenuDescr far& sharedMenu); 

Inserts the server's menu into the composite menu. Determines the number of groups 
and the number of pop-up menu items to insert within each group. The shared menu 
(sharedMenu) is the container's menu merged with the server's menu groups. 


See also TMenuDescr has more information about menu merging, TOcMenuDescr 
struct 


EvOcViewLoadPart 
bool EvOcViewLoadPart(TOcSaveLoad far& ocLoad); 
Asks the server to load itself from storage. Loads the document and its associated view. 


EvOcViewOpenDoc 

bool EvOcViewOpenDoc(const char far* path); 

Asks the container application to open an existing document so the document can 
receive embedded and linked objects. (Actually, TOleView calls on the TOleDocument 
object to read the document from storage, using the standard OLE [Storage and IStream 
interfaces). Assigns a unique string identifier to the document and returns true if 
successful. 


See also TOleView::EvOcViewClose 


EvOcViewPartinvalid 

bool EvOcViewPartinvalid(TOcChangelnfo far& changelnfo); 

Notifies the active view of any changes made to the embedded object's data (changelnfo). 
Also, notifies any other views associated with this document that the bounding 
rectangle for the document is invalid and needs to be repainted. EvOcViewPartInvalid 
always returns true. 


EvOcViewSavePart 

bool EvOcViewSavePart(TOcSaveLoad far& ocSave); 

Asks the server to save the embedded object's data to storage. To save the object, 
EvOcViewSavePart calls upon the TOleDocument object, which creates storage as 
necessary for each embedded object. Saves the dimensions of the server's view, which 
the server uses to tell the container how to redraw the embedded object in the 
container's window. | 
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TOleWindow class | | | | 
Seealso TOleView::EvOcViewClose, TOleView::EvOcViewOpenDoc, TOleDocument 


VnDocOpened 
bool VnDocOpened (int omode); 


Ensures that TOleView's data members such as DragPart, Pos, and Scale are initialized 
properly after a revert operation, which cancels any changes made to the document 
since the last time the document was saved to storage. 


VninvalidateRect 
bool VninvalidateRect(LPARAM p): : 

_ Invalidates the view region specified by p. Use this function to invalidate the bounding 
rectangle surrounding an embedded object if the object has been changed, usually as a 
result of in-place editing. If successful, returns true. 


Response table entries 


EV_OC_VIEWOPENDOC EvOcViewOpenDoc 
EV_OC_VIEWINSMENUS EVOcViewInsMenus 
EV_OC_VIEWCLOSE ~~ EvOcViewClose 
EV_OC_VIEWSAVEPART EvOcViewSavePart 
EV_OC_VIEWLOADPART | EvOcViewLoadPart 


EV_OC_VIEWATTACHWINDOW — EvOcViewAttachWindow 


TOleWindow class olewindo.h 


Derived from TWindow, TOleWindow provides support for embedding objects in a 
compound document and serves as the client of a frame window. A compound 
document, such as the one TOleWindow supports, can contain many different types of 

_ embedded objects, from spreadsheets to bitmaps. In addition to providing support for a 
variety of basic window ones TOleWindow also implements several OLE-related 
operations, among them, 


e Responding to drag and drop events 


e In-place editing (the process whereby an embedded object can be edited without 
having to switch to its associated server application) 


¢ Activating an embedded object's server application 
¢ Creating views for the container application. 


_ ¢ Transmitting a document's scaling information between a container's and a server's 
view windows. 


TOleWindow has the ability to determine whether it's actiing as a server or a container. If 
it is a container, TOleWindow has a pointer to aTOcView or if it is a server, TOleWindow 
establishes a pointer to a TOcRemView. From the server's point o of view, every remote 
view has a corresponding TOleWindow. 
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Through its many event-handling member functions, TOleWindow communicates with 
ObjectComponents to implement container and server support for embedded objects, 
update views, and respond to a variety of menu commands associated with the typical 
command identifiers (for example, CM_FILEMENU). It also supports OLE-specific 
verbs such as those activated fromthe Edit menu (for example, Edit and Open). These 
commands and verbs can originate from various sources such as a menu selection, a 
radio button, or even an internal program message. 


Conversely, ObjectComponents talks to ObjectWindows by means of the various 
EV_OC_Xxxx messages. Some of these messages, such as 
EV_OC_VIEWPARTINVALID, implement container support while others, such as 
EV_OC_VIEWCLOSE, implement server support. 


For any user-defined classes derived from TOleWindow, you need to choose which 
functions are appropriate. If you want to provide additional server support, you need to 
define only those functions that implement server messages; if you want to provide 
container support, you need to define only those functions that provide additional 
container support. 


For example, the data embedded in the container application (a compound document 
having one or more embedded objects) and the data embedded in the server application 
(a single OLE object with or without other embedded objects) can be written to storage 
and loaded from storage. If you're using TOleWindow without TOleView, you have to 
manipulate the storage by talking directly to the ObjectComponents class, 
TOcDocument. 


In addition to communicating with ObjectComponents classes, TOleWindow supports 
many transactions as a result of its interaction with other ObjectWindows classes. By 
virtue of its derivation from TWindow, naturally it inherits much of TWindow's 
functionality. 


See also 
TOcView, TWindowView, TWindow 


Public constructor and destructor 


Constructor 

Constructor TOleWindow(TWindow* parent = 0, TModule* module = 0); 

Constructs a TOleWindow object associated with the specified parent window and 
module instance. 


Destructor 
~TOleWindow(); 


Checks to see if there are any open views, and, if no open views exist, destroys the 
TOleWindow object. 


Public member functions 


Deactivate 
virtual bool Deactivate(); 
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If an srabedded object is no longer the active embedded object, either because the user 
has ended an in-place editing session or because the user has clicked outside the 
embedded object, call Deactivate to unselect the object. Returns true if successful. 


GetOcApp 

TOcApp* GetOcApp(); 

Returns the ObjectComponents application associated with this window. eee 
ObjectComponents application that supports linking and embedding has an associated 
TOcApp object. 


Seealso TOcApp 


GetOcDoc 

TOcDocument* GetOcDoc(); i 
Returns the ObjectComponents document associated with this window. This document 
can be either a container's or a server's document. If this is a TOcDocument created by 
the container, the document is an entire compound document, which may consist of one 
or more embedded objects. If this is a TOcDocument created by the server, the document 
is a single OLE object's data. 


Seealso TOcDocument 


GetOcRemView | 

TOcRemView* GetOcRemView(); | 

Returns the server's view associated with this window. In order to draw the OLE object 
in the container's window, the server creates a remote view. 


Seealso TOcRemView 


GetOcView 

TOcView* GetOcView(); | 

Points to the ObjectComponents container view associated with this window. The 
container view holds the compound document (that is a document containing one or 
more embedded objects). 


* Seealso TOcView 
HasActivePart 


bool HasActivePart(); 
Returns true if the container's view holds an in-place active embedded object. 


Seealso TOcView::GetActivePart, InvalidatePart 

PaintMetafile 

virtual void PaintMetafile(TDC& dc, bool erase, TRect& rect); | : 
Repaints the area of the server where the embedded object resides. The dc parameter 


points to the device context. erase is true if the background of the embedded object is to 
be repainted. rect refers to the area to be repainted. 


Seealso InvalidatePart 
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Protected data members 


ContainerName 

string ContainerName; 

Holds the name of the container. The server displays the container's name when an 
embedded object is being edited in the server's window (referred to as out-of-place 
editing). 

DragDC 


TDC* DragDC; 
Points to the DC used while an object is being dragged. 


Seealso DragPt 


DragHit 

TUlHandle::TWhere DragHit; 

Indicates the position in the embedded object where the user points and clicks the 
mouse. This can be any one of the TUIHandle::TWhere enumerated values, for example, 
TopLeft, TopCenter, TopRight, MidLeft, MidCenter, MidRight, BottomLeft, 
BottomCenter, BottomRight, or Outside when no dragging is taking place. 


See also: TUIHandle:: [Where enum 


DragPart 
TOcPart* DragPart; | 
Points to the embedded object (the part) being dragged. 


DragPt 
TPoint DragPt; 
Indicates the point (in logical units) where the mouse is over the dragged object. 


seealso DragDC 


DragRect 
TRect DragRect; 
Holds the rectangle being dragged. 


Seealso DragDC 


DragStart 
TPoint DragStart; 
Holds the point where the dragging of the embedded object began. 


See also DragPt 


Embedded 

bool Embedded; 

Is true if this TOleWindow is an embedded window. As a result, a TocRemView is created 
because the data is being displayed in a server's window. : 


OcApp 
TOcApp* OcApp; 
‘Holds the ObjectComponents application associated with this TOleWindow. 
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See also TOcView::OcApp, TOcApp 


OcDoc | 
TOcDocument* OcDoc; 
Holds the ObjectComponents document associated with this TOleWindow. 


See also TOcDocument, TOcView::OcDocument 


OcView 
TOcView* OcView; 


Holds the ObjectComponents view or remote view (the server 's) associated with the 
TOleWindow view. | 


See also TOcView 


Pos 

TRect Pos; 

Holds the current area in the window where the object is enbedded. Pos reflects the 
area where the object is moved if you move the object. 


Scale 

TOcScaleFactor Scale; 

Holds the current scaling factor. The server uses this information to determine how to 
scale the document. 


Seealso TOcScaleFactor, EvOcViewGetScale, SetScale 


TOleWindow::ShowObjects 

bool ShowObjects; 

Is true if the embedded object's frame (the grey or shaded brushes around the object) is 
displayed. The frame can be turned on or off depending on how you want the object to 
appear. | 


Protected member functions 


CanClose 

bool CanClose(); 

Returns true if the window can be closed. Checks all the server's child windows’ 
CanClose functions, which must return true before the window can be closed. 
Terminates any open editing transactions before closing the window; otherwise, ‘Passes 
control to TWindow::CanClose. 


CeEditConvert 

void CeEditConvert(TCommandEnabler8); | 

Enables a command with an ID of CM_EDITCONVERT, which iets the user convert ae 
selected object from one format to another. This is an OLE-specific pop-up menu option. 


CeEditCopy 

void CeEditCopy(TCommandEnabler&): 

Enables a command with an ID of CM_EDITCOPY, which lets the user so selected 
object to the Clipboard. 
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CeEditCut 

void CeEditCut(TCommandEnabler&): 

Enables a command with an ID of CM_EDITCUT, which lets a user copy and delete the 
selected object from the view. 


CeEditDelete 

void CeEditDelete(TCommandEnabler&); 

Enables a command with an ID of CM_EDITDELETE, which lets the user delete the 
selected object from the view. 


CeEditinsertObject 

void CeEditInsertObject(TCommandEnabler&); 

Enables a command with an ID of CM_EDITCUT, which lets the user cut a section of 
text from the view. 


CeEditLinks 

void CeEditLinks(TCommandEnabler&); 

Enables a command with an ID of CM_EDITLINKS, which lets the user manually 
update the list of linked items in the current view. 


CeEditObject 

void CeEditObject(TCommandEnabler&); 

Enables a command with an ID of CM_EDITOBJECT, which lets the user edit the 
embedded object. 


CeEditPaste 

void CeEditPaste(TCommandEnabler&); 

Enables a command with an ID of CM_EDITPASTE, which lets the user paste the 
embedded object from the Clipboard. 


CeEditPasteLink 

void CeEditPasteLink(TCommandEnabler&); 

Enables a PasteLink command with an ID of CM_EDITPASTELINK, which lets the user 
link to the embedded object on the Clipboard. See the ocrxxxx Clipboard constants for a 
description of the available Clipboard formats. 


Seealso TOleWindow::CeEditPasteSpecial, ocrxxxx Clipboard constants 


CeEditPasteSpecial 

void CeEditPasteSpecial(TCommandEnabler&); 

Enables the PasteSpecial command, which lets the user select a Clipboard format to be 
pasted or paste linked. See the ocrxxxx Clipboard constants for a description of the 
available Clipboard formats. 


See also TOleWindow::CeEditPasteLink, ocrxxxx Clipboard Constants 
CeEditVerbs 
void CeEditVerbs(T CommandEnabler& ce); 


Enables the Edit | Verbs command, which lets the user select one of the OLE-specific 
verbs from the Edit menu: for example, Edit, Open, or Play. 7 
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CeFileClose 
void CeFileClose(TCommandEnabler& ce); : 
_ Enables the FileClose command, which lets the user exit from the window view. 


CleanupWindow 

void CleanupWindow(); | | 
Performs normal window cleanup and informs the TOcView object that the window is 
closed. 


Seealso TWindow::CleanupWindow, TOcView 


CmEditConvert 

void CmEditConvert(); 

Responds to a command with an ID of CM_ EDITCONVERT by converting an object 
from one type to another. 


CmEditCopy 

void CmEditCopy(); 

Responds to a command with an ID of CM_EDITCOPY by copying the selected text to 
the Clipboard. 


CmEditCut 

void CmEditCut(); 

Responds to a command with an ID of CM_EDITCUT by copying the selected text to 
the Clipboard before cutting the text. 


CmEditDelete 
void CmEditDelete(); 
Responds to a command with an ID of CM_EDITDELETE by deleting the selected text. 


CmEditinsertObject 
void CmEditlnsertObject(); 

Responds to a command with an ID of CM_EDITINSERTOBJECT by neers a an object 
that a user selects from a list of object types. 


CmEditLinks 
void CmEditLinks(); 
Responds to a command with an ID of CM_EDITLINKS by updating the user-selected 
list of linked items in the current view. | 


CmEditPaste 

void CmEditPaste(); 

Responds to a command with an ID of CM_EDITPASTE by pasting an object from the 
Clipboard into the document. 


‘CmEditPasteLink 

void CmEditPasteLink(); 

Responds to a command with an ID of CM_EDITPASTELINK by eatae a link 
_ between the current document and the object on the Clipboard. 


Seealso TOleWindow::CmEditPasteSpecial, ocrxxxx Clipboard constants _ 


332 ObjectWindows Reference Guide 


TOleWindow class 


CmEditPasteSpecial 

void CmEditPasteSpecial(); 

Responds to a command with an ID of CM_EDITPASTESPECIAL by letting the user 
select an object from a list of available formats for pasting from the Clipboard onto the 
document. 


Seealso TOleWindow::CmEditPasteLink, ocrxxxx Clipboard constants 


CmFileClose 

void CmFileClose(); 

Responds to a command with an ID of CM_FILECLOSE by posting a WM_CLOSE 
message to the parent window to close the application. 


CreateOcView 

virtual TOcView* CreateOcView(TDocTemplate* tpi, bool isEmbedded, IUnknown* outer); 

Creates an ObjectComponents view associated with the embedded object. Associates 
the view with the document template specified in tpl. If isEmbedded is true, a remote 
view is created (that is, a TOcRemView instead of a TOcView). The outer parameter refers 
to the [Unknown interface with which the view will aggregate itself. 


Seealso TOcView, TOcRemView 


CreateVerbPopup 

TPopupMenu* CreateVerbPopup(const TOcVerb& ocVerb); 

Creates and enables a pop-up menu option (ocVerb) on the Edit menu. The verb 
describes an action (for example, Edit, Open, Play) that is appropriate for the embedded 
object. 


Seealso EvDoVerb 


EvCommand 

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode); 

Overrides the usual EvCommand message to handle the OLE verbs from 
CM_EDITFIRSTVERB to CM_EDITLASTVERB. These commands, which are defined in 
oleview.rh, correspond to the OLE-specific Edit menu selections such as Edit, Open, and 
Play. All of the other commands are passed to TWindow::EvCommand for normal 
processing. | 


Seealso CM _ xxxx edit view constants, TOleWindow::EvCommandEnable, 
TWindow::EvCommand 


EvCommandEnable 

void EvCommandEnable(TCommandEnabler& commandEnabler); 

Overrides the usual EvCommandEnable message in order to enable the OLE verbs from 
CM_EDITFIRSTVERB to CM_EDITLASTVERB. These commands enable the OLE- 
specific Edit menu selections, such as Edit, Open, and Play. All of the other commands 
are passed to TWindow::EvCommand for normal processing. 


Seealso TOleWindow::EvCommand, TWindow::EvCommand 


EvDoVerb 
void EvDoVerb(uint whichVerb); 
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Executes an OLE-related menu option fom the Edit: menu esi example, Edit, Copy, or 
Play) that is associated with the selected object. _ | 


See also CreateVerbPopup 


EvLButtonDbiClk 

void EvLButtonDbiClk(uint modKeys, TPoint& point); 

Responds to a mouse button double-click message. Fol ButtonDbICIk performs hit 
testing to see which embedded object, if any, is being clicked on, then eee activates 
the embedded Peaee 


EvLButtonDown 

void EvLButtonDown(uint modkeys, TPoint& point); 

Responds to a left button down message by beginning a mouse drag transaction at the 
given point. Performs additional hit testing to see which embedded object, if any, is 
being clicked on. The modKeys parameter holds the values for a key combination such as 
a shift and double click of the mouse button. 


See also EvRButtonDown 


EvLButtonUp 

void EvLButtonUp(uint modKeys, TPoint& point); 

Responds to a left button up message by ending a mouse drag action. point refers to the 
place where the mouse is located. modKeys holds the values for a combined key and 
mouse transaction. | 


EvMDiActivate 

void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated); 

Responds to a message forwarded from the MDI child window (if one exists) and lets 
the TOcView class know that the view window child:-window frame has been activated 
or deactivated. 3 


The hWndActivated parameter contains a handle to the MDI child window being — 
activated. Both the child window being activated being activated and the child window 
(hWndDeactivated) being deactivated receive this message. - 


Seealso TOcView 


EvMouseMove 

void EvMouseMove(uint, TPoint& point); 

Responds to a mouse move message with the appropriate transaction. If the mouse is 
being dragged, the embedded object is moved. If a resizing operation occurs, then the 
embedded object is resized. This message is handled only when a mouse dragging or 
resizing action involving the embedded object occurs. 


_ EvOcEvent 
LRESULT EvOcEvent(WPARAM wParam, LPARAM |Param); 
Responds to a WM_OCEVENT message and subdispatches the message based on 
wParam. ObjectComponents sends WM_OCEVENT messages when it needs to 
communicate with an OLE-generated event; for example, if a server wants to display 
toolbars. | 
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EvOcPartinvalid 

bool EvOcPartinvalid(TOcPart far&): 

Handles a WM_OCEVENT message concerning the embedded or linked object in the 
document and invalidates the part. 


If the TOleWindow object is unable to handle the message, EvOcPartInvalid returns false. 


EvOcViewAttachWindow 

bool EvOcViewAttachWindow(bool attach); 

Attaches the view to its ObjectWindows parent window so that the user can perform 
open editing on the embedded object, or if the embedded object has been deactivated 
while in-place editing was occurring. 


If the TOleWindow object is unable to handle the message, EvOcViewAttachWindow 
returns false. 


EvOcViewBorderSpaceReq 
bool EvOcViewBorderSpaceReq(TRect far*): 
Requests that the server create space for a tool bar in the view of an embedded object. 


If the TOleWindow object is unable to handle the message, EvOcViewBorderSpaceReq 
returns false, the default value. 


See also EvOcViewBorderSpaceSet 


EvOcViewBorderSpaceSet 

bool EvOcViewBorderSpaceSet(TRect far*): 

Requests that the server's tool bar be placed in the container's view of an embedded 
object. 


If the TOleWindow object is unable to handle the message, EvOcViewBorderSpaceSet 
reurns false, the default value. | 


See also §EvOcViewBorderSpaceReq 


EvOcViewClipData 
HANDLE EvOcViewClipData(TOcFormat far&); 
Requests Clipboard data in the format specified. 


If the TOleWindow object is unable to handle the message, EvOcViewClipData returns 
false. 


EvOcViewClose 
bool EvOcViewClose(); 
Asks the server to close a currently open document and its associated view. 


If the TOleWindow object is unable to handle the message, EvOcViewClose returns false. 


EvOcViewDrag 

bool EvOcViewDrag(TOcDragDrop far&); 

Handles an OC_VIEWDRAG message asking the container to provide visual feedback 
_while the user is dragging the embedded object. 


If the TOleWindow object is unable to handle the message, EvOcViewDrag returns false. 
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EvOcViewDrop | 
bool EvOcViewDrop(TOcDragDrop far8); 
Requests a given object be dropped at a specified place on the container's window. _ 


If the TOleWindow object is unable to handle the message, EvOcViewDrop returns false. 


EvOcViewGetPalette 
bool EvOcViewGetPalette(LOGPALETTE far* far* palette); 
Requests the color palette to draw the object. 


If the TOleWindow object is unable to handle the message, EvOcViewGetPalette returns 
false. 


EvOcViewGetScale 

bool EvOcViewGetScale(TOcScaleFactor& scaleFactor); 

Responds to an OC_VIEWGETSCALE message and gets the scaling for the server 
objectj, causing the embedded object to be displayed using the correct scaling value (for 
example, 120%). scaleFactor indicates the scaling factor, the ratio between the size of the 
embedded object and the size of the site where the object is to be displayed. ~ 


It the TOleWindow object is unable to handle the message, EvOcViewGetScale returns 
false. 


Seealso Scale, TOcScaleFactor 


' EvOcViewGetSiteRect 
bool EvOcViewGetSiteRect(TRect far* rect); 
Gets the size of the rectangle (the site) where the embedded object is to be placed. rect 
refers to the size of the bounding rectangle that encloses the embedded object. 


Seealso EvOcViewSetSiteRect 


EvOcViewInsMenus 

bool EvOcViewlnsMenus(TOcMenuDescr far&); 

Requests that the menus in a composite menu (a menu composed of both the server's 
and the container's menus). 


If the TOleWindow object is unable to handle the message, EvOcViewInsMenus returns 
false. 


EvOcViewLoadPart 
bool EvOcViewLoadPart(TOcSaveLoad far* ocLoad); 
Requests that an embedded object load itself. 


If the TOleWindow object is unable to handle the message, EvOcViewLoadPart returns 
false. 


EvOcViewOpenDoc 

bool EvOcViewOpenDoc(const char far*); 

Asks the container to open an existing document, which will be used for linking from 
the embedding site. 


If the TOleWindow object is unable to handle the message, EvOcViewOpenDoc returns 
false. 
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EvOcViewPaint 
bool EvOcViewPaint(TOcViewPaint far&); | 
Asks the server to paint an object at a given position on a specified device context. 


If the TOleWindow object is unable to handle the message, EvOcViewPaint returns false. 


EvOcViewPartinvalid 

bool EvOcViewPartinvalid(TOcChangelnfo far& changelnfo); 

Informs an active container that one of its embedded objects needs to be redrawn. 
Changes in the container's part should be reflected in any other, non-active views. 
Returns true after all views have been notified of the necessary changes. 


If the TOleWindow object is unable to handle the message, EvOcViewPartInvalid returns 
false. 


EvOcViewPartSize 

bool EvOcViewPartSize(TRect far*); 

The server asks itself the size of its current rectangle and lets the container know about 
the size of the server's view in pixels. 


If the TOleWindow object is unable to handle the message, EvOcViewPartSize returns 
false. 


EvOcViewSavePart 

bool EvOcViewSavePart(TOcSaveLoad far& ocSave); 

Asks the server to write an embedded object's data (the part as represented by the ocSave 
parameter) into storage. 


If the TOleWindow object is unable to handle the message, EvOcViewSavePart returns 
false. 


EvOcViewScroll 

bool EvOcViewScroll(TOcScrollDir); 

Asks the container to scroll the view window and updates any internal state as needed. 
EvOcViewScroll is called when the server is resizing or a drop interaction occurs near the 
edge of the window. 


If the TOleWindow object is unable to handle the message, EvOcViewScroll returns false. 


EvOcViewSetScale 

bool EvOcViewSetScale(TOcScaleFactor& scaleFactor); 

Responds to an OC_VIEWSETSCALE message and handles the scaling for server 
application, ensuring that the embedded object is displayed using the correct scaling 
values (for example, 120%). The server uses this value in its paint procedure when the 
embedded object needs to be redrawn. scaleFactor indicates the scaling factor, the ratio 
between the size of the embedded object and the size of the site where the object is to be 
displayed. 


If the TOleWindow object is unable to handle the message, EvOcViewSetScale returns 
false. 


Seealso EvOcViewGetScale, TOcScaleFactor 


Chapter 2, ObjectWindows library reference 337 


TOleWindow class 


EvOcViewSetSiteRect : 

bool EvOcViewSetSiteRect(TRect far* rect); 

Converts the rect to logical units. This area, referred to as the site, is measured in logical 
units that take into account any scaling factor. rect refers to the size of the bounding 
rectangle that encloses the embedded object. 


_Seealso EvOcViewGetSiteRect 


EvOcViewSetTitle 
void EvOcViewSetTitle(const char far* title); 


Sets the window's caption to title. The new caption is the name of the in-place active 
server merged with the caption of the container's window. 


In the case of an MDI child window, the new caption is the in-place server's name 
merged with the caption of the MDI child window. When the child window is 
maximized, the merged caption is appended to the end of the main frame window's 
caption. 


EvOcViewShowTools 

bool EvOcViewShowTools(TOcToolBarInfo far& thi); 

Asks the server to provide its tool bars for display in the container's window. Returns 
true if tool bars are supplied. : 


If the TOleWindow object is unable to handle the message, EvOcViewShowTools returns 
false. 


EvOcViewTitle 

const char far* EvOcViewTitle(); 

Asks the container for the caption in its frame window. Returns the frame window's 
caption. 


EvRButtonDown 

void EvRButtonDown(uint modKeys, TPoint& point); 

Responds to a right button down message. Performs additional hit testing to see which 
embedded object, if any, is being clicked and displays a local menu with appropriate 
options for the embedded object. 


point refers to the place where the mouse is located. modKeys holds the values for a 
combined key and transaction, such as a Shift+double-click of the mouse button. 


See also EvLButtonDown 


EvSetCursor 
bool EvSetCursor(HWND, uint hitTest, uint); 
Performs hit testing to tell where the cursor is located within the window and what 
object the cursor is moving over. If the cursor is within an embedded object, 
_ EvSetCursor changes the shape of the cursor. 


When the cursor is over an inactive part and not ona handle, EvSetCursor uses an arrow 
cursor. If the cursor is on one of the handles of the embedded part, EvSetCursor changes 
the cursor to a resizing cursor. 
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EvSetFocus 

void EvSetFocus(HWND hWndLostFocus); 

Responds to a change in focus of the window. hWndLostFocus contains a handle to the 
window losing the focus. EvSetFocus checks to see if an in-place server exists and, if so, 
passes the focus to the in-place server. 


EvSize 

void EvSize(uint sizeType, TSize& size); 

Passes the event to TWindow::EvSize for normal processing and forwards the event to 
TOcView::EvResize to let a possible in-place server adjust its size. 


Seealso TOcView::EvSize 


GetinsertPosition 

virtual void GetinsertPosition(TRect& rect); 

Gets the position (rect) where the embedded object is inserted. You need to override this 
function if you want to override any default position. 


GetLogPerUnit 

virtual void GetLogPerUnit(TSize& logPerUnit); 

Gets the logical units (typically pixels) per inch for a document so that the document's 
embedded objects can be painted correctly on the screen DC. 


Init 

void Init(); 

Initializes the TOleWindow object with the appropriate window style and initializes the 
necessary data members (for example, sets the accelerator ID to IDA_OLEVIEW). 


InvalidatePart 

virtual void InvalidatePart(TOcInvalidate invalid); 

Invalidates the area where the embedded object exists. The server uses this function to 
tell OLE that the part (the embedded object), has changed. OLE then asks the server to 
redraw the part into a new metafile so that OLE can redraw the object for the container 
application even when the server application is not active. 


Seealso PaintMetafile, TOcView_GetActivePart 


Paint 
void Paint(TDC& dc, bool erase, TRect& rect); 
Repaints the window's contents and tells each embedded object to repaint itself. 


dc points to the paint DC. erase indicates whether the background should be erased. rect 
is a reference to the bounding rectangle of the area that needs repainting. 


PaintParts 

virtual bool PaintParts(TDC& dc, bool erase, TRect& rect, bool metafile); 

Repaints the embedded objects on the given DC. The erase parameter is true if the 
background of the embedded object is to be repainted. rect indicates the area that needs 
repainting. metafile indicates whether or not the DC represents a metafile. 


Select 
virtual bool Select(uint modKeys, TPoint& point); 
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Selects the embedded object at the specified point (measured in aed To) Returns 
true if the object is captured by the mouse drag; otherwise, returns false. 


SelectEmbedded 

bool SelectEmbedded(); - 

Selects the embedded object and returns true to indicate that the object has been 
selected. 


SetScale 
virtual void SetScale(uinti6 percent); — | 
Sets the ratio of the embedded object's size to the size of the site. 


See also SetupDC 


The area inside the container where the embedded object will be drawn 


SetSelection 

void SetSelection(TOcPart* part); 

Selects the embedded object indicated in the part parameter. When the embedded object 
is selected, a selection box is drawn around the area. After an embedded object is 
selected, the user can perform operations on the embedded object: for example, moving, 
sizing, or copying the embedded object to the Clipboard. 


Setup DC 
virtual void SetupDC(TDC& dc, bool scale = true); : | 
Determines the viewport's origin and extent (the logical coordinates and the size of the 
DC). Sets up the device context (DC) before painting the embedded object. dc refers to 

_ the DC and scale indicates that the scaling factor to use when painting the embedded 
object is a ratio between the site and the embedded object. 


See also TOcScaleFactor, SetScale 


SetupWindow 

void SetupWindow(); 

Establishes a connection between the TOcView object and the view's HWND so the view 
can send notification messsages to the window. 


Vninvalidate Rect 

bool VninvalidateRect(LPARAM p); 

When the embedded object is modified, VnInvalidateRect sends a message to the View 
portion of the Doc/View pair. When TOleWindow receives this message, the view region 
is marked for erasing. VnInvalidateRect always returns true. 
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EV_WM_ LBUTTONDOWN 
EV_WM RBUTTONDOWN 
EV_WM LBUTTONDBLCLK 


EV_WM_MOUSEMOVE 
EV_WM_LBUTTONUP 
EV_WM_SIZE 
EV_WM_MDIACTIVATE 
EV_WM_SETFOCUS 
EV_WM_SETCURSOR 


EV_COMMAND(CM_EDITDELETE, CmEditDelete) 
EV_COMMAND_ENABLE(CM_EDITDELETE, CeEditDelete) 
EV_COMMAND(CM_EDITCUT, CmEditCut) 

EV_COMMAND _ENABLE(CM_EDITCUT, CeEditCut) 
EV_COMMAND(CM_EDITCOPY, CmEditCopy) 

EV_COMMAND._ ENABLE(CM_EDITCOPY, CeEditCopy) 
EV_COMMAND(CM_EDITPASTE, CmEditPaste) 
EV_COMMAND_ENABLE(CM_EDITPASTE, CeEFditPaste) 
EV_COMMAND(CM_EDITPASTESPECIAL, CmEditPasteSpecial) 
EV_COMMAND_ ENABLE(CM_EDITPASTESPECIAL, CeEditPasteSpecial) 
EV_COMMAND(CM_EDITPASTELINK, CmEditPasteLink) 
EV_COMMAND_ENABLE(CM_EDITPASTELINK, CeEditPasteLink) 
EV_COMMAND(CM_EDITINSERTOBJECT, CmEditInsertObject) 
EV_COMMAND_ENABLE(CM_EDITINSERTOBJECT, CeEditInsertObject) 
EV_COMMAND_ENABLE(CM_EDITLINKS, CeEditLinks) 
EV_COMMAND(CM_EDITLINKS, CmEditLinks) 
EV_COMMAND_ENABLE(CM_EDITOBJECT, CeEditObject) 
EV_COMMAND_ENABLE(CM_EDITCONVERT, CeEditConvert) 
EV_COMMAND(CM_EDITCONVERT, CmEditConvert) 
EV_COMMAND(CM_ EXIT, CmFileClose) 
EV_COMMAND_ENABLE(CM_ EXIT, CeFileClose) 
EV_MESSAGE(WM_OCEVENT, EvOcEvent) 
EV_OWLNOTIFY(vniInvalidate) 

EV_OC_VIEWPARTINVALID 


EV_OC_VIEWSETTITLE 
EV_OC_VIEWTITLE 


EV_OC_VIEWBORDERSPACEREQ 
EV_OC_VIEWBORDERSPACESET 


EV_OC_VIEWDROP 
EV_OC_VIEWDRAG 
EV_OC_VIEWSCROLL 
EV_OC_VIEWGETSCALE 
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a Member function _ ee ~ 
- EvLButtonDown 


EvRButtonDown 
EvLButtonDbIClk 
EvMouseMove 
EvLButtonUp 
EvSize 
EvMD!IActivate 
EvSetFocus 
EvSetCursor 
CmEditDelete 
CeEditDelete 
CmEditCut 
CeEditCut 
CmEditCopy 
CeEditCopy 
CmEditPaste 
CeEditPaste 
CmEditPasteSpecial 
CeEditPasteSpecial 
CmEditPasteLink 
CeEditPasteLink 
CmEditInsertObject 
CeEditInsertObject 
CeEditLinks 
CmEditLinks 
CeEditObject 
CeEditConvert 
CmEditConvert 
CmFileClose 
CeFileClose 
EvOcEvent 
VnInvalidateRect 
EvOcViewPartInvalid 
EvOcViewSetTitle 
EvOcView Title 
EvOcViewBorderSpaceReq 
EvOcViewBorderSpaceSet 
EvOcViewDrop 
EvOcViewDrag 
EvOcViewScroll 
EvOcViewGetScale 
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EV_OC_VIEWSETSITERECT | EvOcViewSetSiteRect 
EV_OC_VIEWPAINT EvOcViewPaint 
EV_OC_VIEWSAVEPART EvOcViewSavePart 
EV_OC_VIEWLOADPART EvOcViewLoadPart 
EV_OC_VIEWINSMENUS | EvOcViewInsMenus 
EV_OC_VIEWSHOWTOOLS, EvOcViewshowTools 
EV_OC_VIEWGETPALETTE | EvOcViewGetPalette 
EV_OC_VIEWCLIPDATA, t « | EvOcViewclipData 
EV_OC_VIEWCLOSE | EvOcViewClose 

~ EV_OC_VIEWPARTSIZE EvOcViewPartSize 
EV_OC_VIEWOPENDOC 7 EvOcViewOpenDoc 
EV_OC_VIEWATTACHWINDOW EvOcViewAttachWindow 
EV_OC_VIEWSETSCALE | | EvOcViewSetScale 

TOpenSaveDialog class — opensave.h 


TOpenSaveDialog is the base class for modal dialogs that let you open and save a file ~ 

under a specified name. TOpenSaveDialog constructs a TData structure and passes it the 

TOpenSaveDialog constructor. Then the dialog is executed (modal) or created (modeless). 

Upon return, the necessary fields are updated, including an error field that contains 0, or 
-a common dialog extended error. 


Public constructor 


Constructor 
TOpenSaveDialog(TWindow* parent, TData& data, TResld templateld = 0, const char far* title = 0, 
TModule* module = 0); 


Constructs an open save dialog box object with the supplied parent Nindow: data, 
resource ID, title, and current module object. 


Seealso JData struct 


Public member functions 


GetFileTitle | | 
static int GetFileTitle(const char far* fileName, char far* fileTitle, int fileTitleLen) 
Stores the name of the file to be saved or opened. 


GetFileTitleLen 
static int GetFileTitleLen(const char far* fileName); 
Stores the length of the file name to be saved or opened. 
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Protected data members 


Data 

TData& Data; 

Stores the file name, its length, extension, filter, initial directory, default file name, 
extension, and any error messages. 


ofn 

OPENFILENAME ofn; 

Contains the attributes of the file name such as length, extension, and directory. ofn is 
initialized using the fields in the TOpenSaveDialog::TData class. This member is not 
available under Presentation Manager. 


Seealso Data struct 


ShareViMsgld 

static uint ShareViMsgld; 

Contains the message ID of the registered ShareViolation message. This member is not 
available under Presentation Manager. 


Seealso TData struct, ShareViolation 


Protected constructor 


Constructor 

TOpenSaveDialog(TWindow* parent, TData& data, TModule* module); 

Constructs a TOpenSaveDialog box object with the supplied parent, data, and current 
module object. 


Seealso Data struct 


Protected member functions 


CmLbSelChanged 

void CmLbSelChanged(); 

Indicates that the selection state of the e file name list box in the GetOpenFileName or 
GetSaveFileName dialog boxes has changed. CmLbSelChanged is a default handler for 
command messages sent by Ist1 or Ist2 (the file and directory list boxes, respectively). 


CmOk 

void CmOkK(); 

Responds to a click on the dialog box's OK button (with the identifier IDOK). Calls 
CloseWindow (passing IDOK). 


Seealso TDialog::CloseWindow 
DialogFunction 
bool DialogFunction(uint message, WPARAM, LPARAM); 


Returns true if a message is handled, returns ShareViMsgld if a sharing violation occurs, 
otherwise returns false. 
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DoExecute 
int DoExecute(); 
Creates and executes a modal dialog box. 


Init 
void Init(TResid templateld); 
Initializes a TOpenSaveDialog object with the current resource ID. | 


ShareViolation 

virtual int ShareViolation(); 

If a sharing violation occurs when a file is opened or saved, ShareViolation is called to 

obtain a response. The default return value is OFN_SHAREWARN. Other sharing 

violation responses are listed in the following table. This member is not available under 
_ Presentation Manager. 


OFN_SHAREFALLTHROUGH _ Specifies that the file name can be used and that the dialog box should 
return it to the application. 


OFN_OFN_SHARENOWARN __Instructs the dialog box to perform no further action with the file name 
| and not to warn the user of the situation. 


OFN_SHAREWARN 7 This is the default response that is defined as 0. Instructs the dialog box 
| to display a standard warning message. 


Seealso Data struct, ShareViMsgld 


Response table entries 


The TOpenSaveDialog response table has no entries. 


TOpenSaveDialog: :TData struct — - Opensave.h 


TOpenSaveDialog structure contains information about the user's file open or save 
selection. Specifically, this structure stores a user-specified file name filter, file extension, 
file name, the initial directory to use when displaying file names, any error codes, and 
various file attributes that determine, for example, if the file is a read-only file. The 
classes TFileOpenDialog and TFileSaveDialog use the information stored in this structure 
when a file is opened or saved. | 


Public constructors and destructor 


Constructor 
TData(uint32 flags=0, const char* filter=0, char* customFilter=0, char* initialDir=0, char* defExt=0); 
Constructs a TOpenSaveDialog::TData structure. 


Destructor 
~TData(); 
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Destructs a TOpenSaveDialog::TData structure. 
Seealso TEditFile::FileData 


Data members 


CustomFilter 
char* CustomFilter; 
CustomFilter stores the user-specified file filter; for example, *.CPP. 


DefExt 
char* DefExt; 
DefExt stores the default extension. 


Error 
uint32 Error; 
Error contains one or more of the following error codes: 


CDERR_ DIALOGFAILURE. oe Failed t to create a eon box. 
CDERR_LOCKRESOURCEFAILURE Failed to lock a specified resource. 
CDERR_LOADRESFAILURE Failed to load a specified resource. 
CDERR_LOADSTRFAILURE Failed to load a specified string. 
FileName 


char* FileName; 
Holds the name of the file to be saved or opened. 


Filter 
char* Filter; 
Filter holds the filter to use initially when displaying file names. 


Filterindex 
int Filterindex; 
FilterIndex indicates which filter to use initially when displaying file names. 


Flags 
uint32 Flags; 
Flag contains one or more of the following constants: 


| OFN_HIDEREADONLY Hides the read-only check box. 


OFN_FILEMUSTEXIST Lets the user enter only names of existing files in the File Name entry 
field. If an invalid file name is entered, a warning message is displayed. 

OFN_PATHMUSTEXIST Lets the user enter only valid path names. If an invalid path name is 
entered, a warning message is displayed. 

OFN_NOVALIDATE Performs no check of the file name and requires the owner of a derived 


class to perform validation. 
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ets the current directory back to what it was when the dialog was 


, : initiated. 
OFN_ALLOWMULTISELECT Allows multiple selections in the File Name list box. 
OFN_CREATEPROMPT _ Asks if the user wants to create a file that does not currently exist. 


OFN_EXTENSIONDIFFERENT __ Idicates the user entered a file name different from the specified in 
DefExt. This message is returned to the caller. 


OFN_NOREADONLYRETURN _ The returned file does not have the Read Only attribute set and is not in 
a write-protected directory. This message is returned to the caller. 


OFN_NOTESTFILECREATE The file is created after the dialog box is closed. If the application sets: 
this flag, there is no check against write protection, a full disk, an open 
drive door, or network protection. For certain network environments, 
this flag should be set. 


OFN_OVERWRITEPROMPT The Save As dialog box displays a message asking the user if it's OK to 
overwrite an existing file. 


OFN_SHAREAWARE If this flag is set and a call to open a file fails because of a sharing 
violation, the error is ignored and the dialog box returns the given file 
name. If this flag is not set, the virtual function ShareViolation is called, 
which returns OFN_SHAREWARN (by default) or one of the 


following values: 
OFN_SHAREFALLTHROUGH File name is returned from the aidlog box. OFN_SHARENOWARN 
No further action is taken. 
OFN_SHAREWARN User receives the standard warning message for this type of error. 
OFN_SHOWHELP Shows the Help button in the dialog box. 


InitialDir 
char* InitialDir; 
InitialDir holds the directory to use initially when displaying file names. 


Public member functions 


SetFilter 
void SetFilter(const char‘filter = 0): 
Makes a copy of the filter list used to display the file names. 


TOutStream class | docview.h 


Derived from TStream and ostream, TOutStream i is a base class used to create output 
storage streams for a document. 


Public constructor 


Constructor 

TOutStream(TDocumenté& doc, const char far* name, int mode); 

Constructs a TOutStream object. doc refers to the document object, name is the user- 
defined name of the stream, and mode is the mode of opening the stream. 


Seealso TInStream, of XXXX document open enum, shxxx document sharing enum 
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TPaintDC class oe dich 


A DC class derived from TWindowDC that wraps begin and end paint calls for use in a 
WM_PAINT response function. 


Public constructor and destructor 


Constructor 

TPaintDC(HWND wnd); 

Creates a T’PaintDC object with the given owned window. The data member Wn is set 
to wnd. 


Seealso TWindowDC::Wnd, TDC::TDC 
Destructor 


~TPaintDC(); 
Destroys this object. 


Public data member 


Ps 
PAINTSTRUCT Ps; 
The paint structure associated with this TPaintDC object. 


Seealso PAINTSTRUCT struct 
Protected data member 
Wnd 


HWND Whd 
The associated window handle. 


TPalette class | gdiobjec.h 


Form 1 


TPalette is the GDI Palette class derived from TGdiObect. The TPalette constructors can 
create palettes from explicit information or indirectly from various color table types that 
are used by DIBs. 


Public constructors 


Constructors 

TPalette(HPALETTE handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TPalette object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 
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Form 2 — 


Form 3 


Form 4 
Form 5 


— Form6 


Form 7 


Form 8 


Form 9 


TPalette(const TClipboard&); 
Creates a TPalette object with jaliies taken from the given clipboard. 


TPalette(const TPalette& palette); 
This public copy constructor creates a complete copy of the given palette object as in — 


TPalette myPalette = yourPalette; 


TPalette(const LOGPALETTE far* logPalette); 
Creates a TPalette object from the given logPalette array. 


TPalette(const PALETTEENTRY far* entries, int count); 
Creates a TPalette object with count entries from the given entries arrray. 


TPalette(const BITMAPINFO far* info, uint flags = 0); 

Creates a TPalette object from the color table following the given BITMAPINFO 
structure. This constructor works only for 2-, 16-, and 256-color bitmaps. A 0 handle is 
returned for other bitmaps including 24-bit DIBs. 


TPalette(const BITMAPCOREINFO far* core, uint flags = 0); 

Presentation Manager (PM) 1.x DIBs only. Creates a TPalette object from the color table 
following the given BITMAPCOREINFO structure. This constructor works only for 2-, 
16-, and 256-color bitmaps. A 0 handle is returned for other bitmaps including 24-bit 
DIBs. Note that every color in a PM 1.x table must be present because there is no ClrUsed 
field in the DIB header. 


TPalette(const TDib& dib, uint flags = 0); 

Creates a TPalette object from the given DIB object. The flags argument represents the 
values of the data structure used to create the palette. 

TPalette(); 

(Presentation Manager only) Creates a TPalette object that uses the default system palette . 


Seealso = TClipboard::GetClipboardData, TGdiObject:: Handle, TGdiObject::ShouldDelete, 
TPalette::GetPaletteEntries, BITMAPCOREINFO struct, BITMAPINFO struct, 


~LOGPALETTE struct, PALETTEENTRY struct 


Public member functions 


AnimatePalette 

void AnimatePalette(uint start, uint count, const PALETTEENTRY far* entries); 

Replaces entries in this logical palette from the entries array of PALETTEENTRY 
structures. start specifies the first entry to be animated, and count gives the number of 
entries to be animated. The new entries are mapped into the system palette 
immediately. 


Seealso PALETTEENTRY struct 


GetNearestPalettelndex 


_ uint GetNearestPalettelndex(TColor color) const; 


Returns the index of the color entry that pee the best color in this paicte to the 
given color. 


Seealso TColor 
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GetNumEntries 
uint GetNumEntries() const; 
Returns the number of entries in this palette or 0 if the call fails. 


See also TGdiObject::GetObject 


GetObject 

bool GetObject(uint16 far& numEntries) const; 

Finds the number of entries in this logical palette and sets the value in the numEntries 
argument. To find the entire LOGPALETTE structure, use GetPaletteEntries. Returns true 
if the call is successful; otherwise returns false. 


See also TGdiObject::GetObject, TPalette::GetPaletteEntries, LOGPALETTE struct 


GetPaletteEntries 

uint GetPaletteEntries(uint16 start, uinti6 count, PALETTEENTRY far* entries) const; 

Retrieves a range of entries in this logical palette, and places them in the entries array. 
start specifies the first entry to be retrieved, and count gives the number of entries to be 
retrieved. Returns the number of entries actually retrieved, or 0 if the call fails. 


Seealso PALETTEENTRY struct 


GetPaletteEntry 

uint GetPaletteEntry(uint16 index, PALETTEENTRY far& entry) const; | 

Retrieves the entry in this logical palette at index, and places it in the entries array. 
Returns the number of entries actually retrieved: 1 if successful or 0 if the call fails. 


Seealso TPalette::SetPaletteEntry, PALETTEENTRY struct 


operator << 

TClipboard& operator << (TClipboard& clipboard, TPalette& palette); 

Copies the given palette to the given clipboard argument. Returns a reference to the 
resulting clipboard, which allows normal chaining of <<. 


Seealso TClipboard 


operator HPALETTE() 

operator HPALETTE() const; 

Typecasting operator. Converts this palette's Handle to type HPALETTE, which is the 
data type representing the handle to a logical palette. 


ResizePalette 

bool ResizePalette(uint numEntries): 

Changes the size of this logical palette to the number given by numEntries. Returns true 
if the call is successful; otherwise returns false. 


Seealso TPalette:: AnimatePalette 


SetPaletteEntries 

uint SetPaletteEntries(uint16 start, uinti6 count, const PALETTEENTRY far* entries); 

Sets the RGB color values in this palette from the entries array of PALETTEENTRY 
structures. start specifies the first entry to be animated, and count gives the number of 
entries to be animated. Returns the number of entries actually set, or 0 if the call fails. 
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Seealso PALETIEENTRY struct 


SetPaletteEntry | 

uint SetPaletteEntry(uint16 index. const PALETTEENTRY far& entry); 

Sets the RGB color value at index in this palette from the entry argument. start specifies 
the first entry to be animated, and count gives the number of entries to be animated. 
Returns 1 (the number of entries actually set if successful) or 0 if the call fails. 


Seealso PALETTEENTRY struct 


ToClipboard 

void ToClipboard(TClipboard& clipboard); 

Moves this palette to the target clipboard aecmene If a copy is to be put on the 
Clipboard, use TPalette(myPalette).ToClipboard; to make a copy first. The handle in the 
temporary copy of the object will be moved to the clipboard. ToClipboard sets 
ShouldDelete to false so that the object on the clipboard is not deleted. The handle will 
still be available for examination. 


Seealso TClipBoard::SetClipBoardData 


UnrealizeObject 

bool UnrealizeObject(); 

Directs the GDI to completely remap the logical ere to the system palette on the next 
RealizePaletteb-HDC) or TDC: ‘RealizePalette call. Returns true if the call is successful; 
otherwise false. 


See also TDC::RealizePalette ; 


Protected member functions 


Create 
void Create(const BITMAPINFO far’ info, uint flags); 
void Create(const BITMAPCOREINFO far* core, uint flags); 


Sets values in this palette from the given bitmap structure. These functions are usually 
called by the constructor rather than directly. 


See also TBITMAPCOREINFO struct, BITMAPINFO struct 


TPaletteEntry class | | | color.h 


TPaletteEntry is a support class derived from the structure MRE TTEENTRY. The 
latter is defined as follows: 


typedef struct tagPALETTEENTRY { 
uint8 peRed; 
uint8 peGreen; 
uint8 peBlue; 
uint8 peFlags; 
} PALETTEENTRY; 
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Form 1 


Form 2 


TPen class 


where peRed, peGreen, and peBlue specify the red, green, and blue intensity-values for a 
palette entry. | 


The peFlags member can be set to NULL or one of the following values: 


PC_EXPLICIT Specifies that the low-order word of the logical palette entry designates a 
hardware palette index. This flag allows the application to show the contents of 
the display device palette. 


PC_NOCOLLAPSE Specifies that the color be placed in an unused entry in the system palette instead 
of being matched to an existing color in the system palette. If there are no unused 
entries in the system palette, the color is matched normally. Once this color is in 
the system palette, colors in other logical palettes can be matched to this color. 


PC_RESERVED Specifies that the logical palette entry be used for palette animation; this prevents 
other windows from matching colors to this palette entry since the color 
frequently changes. If an unused system-palette entry is available, this color is 
placed in that entry. Otherwise, the color is available for animation. 


TPaletteEntry is used in conjunction with the classes TPalette and TColor to simplify 
logical color-palette operations. Constructors are provided to create TPaletteEntry 
objects from explicit COLORREF and RGB values, or from TColor objects. 


Public constructors 


Constructors 

TPaletteEntry(int r, int g, int b, int f = 0); 

Creates a palette entry object with peRed, peGreen, peBlue, and peFlags set to r, g, b, and f, 
respectively. 


TPaletteEntry(TColor c); 
Creates a palette entry object with peRed, peGreen, peBlue, and peFlags set to r, g, b, and f, 
respectively. 


Seealso tagPALETTEENTRY struct, TPaletteEntry(TColorc), TColor::Red, 
TColor::Green, TColor::Blue 


TPen class gdiobjec.h 


Form 1 


TPen is derived from TGdiObject. It encapsulates the GDI pen tool. Pens can be 
constructed from explicit information or indirectly. TPen relies on the base class’s 
destructor, ~TGdiObject. 


Public constructors 


Constructors 

TPen(HPEN handle, TAutoDelete autoDelete = NoAutoDelete); 

Creates a TPen object and sets the Handle data member to the given borrowed handle. 
The ShouldDelete data member defaults to false, ensuring that the borrowed handle will 
not be deleted when the C++ object is destroyed. 
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Form 2. 


Form 3 


Form 4 


Form 5 


~Formé6 


TPen(T Solon color, int width=1, int style=PS_ SOLID): 

Creates a T’Pen object with the given values. The width argument is in device units, but if 
set to 0, a 1-pixel width is assumed. Sets Handle with the given default values. If color is 
black or white, width is one, style is solid, a stock pen handle is returned. The values for 
style are listed in the following table. 


PS SOLID Creates a solid pen. 

PS_DASH Creates a dashed pen. Valid only when the pen width is one or less in device units. 

PS_DOT Creates a dotted pen. Valid only when the pen width is one or less in device units. 

PS_DASHDOT Creates a pen with alternating dashes dots. Valid only when the pen width is one or 
less in device units. 


PS_DASHDOTDOT _ Creates a pen with alternating dashes double-dots. Valid only when the pen width 
is one or less in device units. 


PS_NULL Creates a null pen. 


PS_INSIDEFRAME _ Createsa solid pen. When this pen is used in any GDI drawing fancion that takes a 
bounding rectangle, the dimensions of the figure will be shrunk so that it fits 
entirely in the bounding rectangle, taking into account the width of the pen. 


TPen(const LOGPEN far* logPen); 
Creates a TPen object from the given logPen values. 


TPen(const Tpen& pen); 
The TPen copy constructor. 


TPen(uint32 penStyle, uint32 width, const TBrush& brush, uint32 styleCount, uint32* sich: 
(32-bit) Creates a TPen object with the given values. 


TPen(uint32 penStyle, uint32 width, const LOGBRUSH8 logBrush, uint32 styleCount, uint32* style); 
(32-bit) Creates a TPen object with the given values. 


— Seealso TColor, TGdiObject::Handle, TGdiObject::ShouldDelete, LOGBRUSH struct, 


LOGPEN struct 


Public member functions 


GetObject 

bool GetObject(LOGPEN far& logPen) const; 

Retrieves information about this pen object and places it in the given LOGPEN structure. 
Returns true if the call is successful, otherwise false. 


See also TGdiObject::GetObject, LOGPEN struct 


operator HPEN() 

operator HPEN() const; 

Typecasting operator. Converts this pen's Handle to DES HPEN (the data type 
representing the handle to a logical pen). 
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TPicResult enum validate.h 


enum TPicResult {prComplete, princomplete, prEmpty, prError, prSyntax, prAmbiguous, princompNoFill}; 
TPicResult is the result type returned by the Picture member function of 
TPXPictureValidator. The result type indicates whether the data entered into the edit 
control matches a specified format. For example, prIncomplete indicates that the data 
entered is missing some information that was specified in the format picture of the data. 


See also 
TPXPictureValidator::Picture 


TPlacement enum gadgetwi.h 


enum TPlacement {Before, After}; 
Enumerates the placement of a gadget. The new gadget i is inserted either before or after 
another gadget. 


You can control the placement of the new gadget by specifying a sibling gadget that the 
new gadget is inserted before or after. If the sibling argument in TGadgetWindow::Insert 
is 0 then the new gadget is inserted at the beginning or the end of the existing gadgets. 

By default, the new gadget is inserted at the end of the existing gadgets. 


Seealso TGadgetWindow::Insert 


TPopupMenu class | | menu.h 


Form 1° 


Form 2 


Form 1 


TPopupMenu creates an empty pop-up menu to add to an existing window or pop-up 
menu. 


Public constructors 


Constructors 
TPopupMenu(TAutoDelete autoDelete = AutoDelete); 
Constructs an empty pop-up menu. 


TPopupMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete); 
Alias constructor for a pop-up menu. 


Public member functions 


TrackPopupMenu 


— bool TrackPopupMenu(uint flags, int x, int y, int rsvd, HWND wnd, TRect* rect = 0); 


Allows the application to create a pop-up menu at the specified location in the specified 
window. flags specifies a screen position and can be one of the TPM_xxxx 
values(TPM_CENTERALIGN, TPM_LEFTALIGN, TPM_RIGHTALIGN, 
TPM_LEFTBUTTON, or TPM_RIGHTBUTTON). wnd is the handle to the window that 
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receives messages about the menu. x specifies the horizontal position in screen 
coordinates of the left side of the menu. y species the vertical position in screen 
coordinates of the top of the menu (for example, 0,0 specifies that a menu's left corner is 
in the top left corner of the screen). rect defines the area that the user can click without 
dismissing the menu. 


Form2 bool TrackPopupMenu(uint flags, TPoint& point, int rsvd, HWND wnd, TRect* rect = 0); 
| This function is the same as the previous i except that the x and y 
positions are specified in point. 
Seealso TPM_xxxx (Windows API) 
TPreviewPage class preview.h 


TPreviewPage displays a page of a document in a print preview window. To obtain the 
information needed to display the page, T’PreviewPage interacts with TPrintPreviewDC 
and T’Printout. Specifically, it creates a TPrintPreviewDC from the window DC provided 
in Paint and passes that TPrintPreviewDC object to TPrintout's SetPrintParams member 
function. The sample pigera PRINT.CPP displays the following sample print preview 
window: 


Select Print Preview to display 
Document window ~ the Print Preview window 


| a Printer Test 


é 1: This text starts af DC arigin* 


SOA STON TNH NSN ANN 


> Preview 


Public constructor 


Constructor 

TPreviewPage(TWindow* parent, TPrintout& printout, TPrintDC& prndc, TSize& printExtent, int pagenum = 1); 
Constructs a T’PreviewPage object where parent is the parent window, printout is a 
reference to the corresponding TPrintout object, prndc is a reference to the 
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TPrintPreviewDC object, printExtent is the extent (width and height) in logical units of 
the printed page, and pagenum is the number of the preview page. TPreviewPage has the 
attributes of a visible child window with a thin border. Sets the background color of the 
preview page window to white. 


Public member functions 


Paint 

void Paint(TDC& dc, bool, TRect& clip); 

Displays the page in the preview window. To determine the preview page's attributes 
(line width, and so on), Paint calls several of TPrintout's member functions. Then, to 
adjust the printer object for previewing, Paint determines if the page fits in the preview 
window or if clipping is necessary. Finally, Paint passes clipping and banding 
information to TPrintout's PrintPage function, which is called to display the page in the 
preview window. 


Seealso T’Printout::BeginPrinting, TPrintout::EndPrinting, TPrintout::PrintPage 


SetPageNumber 
void SetPageNumber(int newNum); 
Sets newNum to the number of the page currently displayed in the preview window. 


Protected data members 


PageNum 
void SetPageNumber(int newNum); 
Sets newNum to the number of the page currently displayed in the preview window. 


PrintDC 
TPrintDC& PrintDC; 
PrintDC& is a handle to the device context to use for printing. 


PrintExtent 
TSize PrintExtent, 
Contains the extent (width and height) in logical units of the page. 


Printout 
TPrintout& Printout; 
Holds a reference to the TPrintout object. 


Protected member functions | 


EvSize 

void EvSize(uint sizeType, TSize& size); 

Invalidates the entire window when the size of the page displayed in the preview 
window changes. 
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Response table entries 


EV_WM_ SIZE EvSize 


TPrintDC class — de.h 


Form 1 


Form 2 


Derived from TDC, TPrintDC provides access to a printer. 


Public constructors 


Constructors 
TPrintDC(HDC handle, TAutoDelete autoDelete = AuioDeielS: 


_ Creates a TPrint object for the DC given by handle. 


TPrintDC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData); 
Creates a TPrint object given print driver, device, output, and data from the DEVMODE 
structure. | 


Seealso TDC, DEVMODE struct 


Public member functions 


AbortDoc 

int AbortDoc(); | 
Aborts the current print job on this printer and erases everything drawn since the last 
call to StartDoc. AbortDoc calls the user-defined function set with TPrintDC::SetAbortProc 
to abort a print job because of error or user intervention. TPrintDC::EndDoc should be 
used to terminate a successfully completed print job. 


If successful, AbortDoc returns a positive or zero value; otherwise a negative value is 
returned. 


Seealso § J’PrintDC::EndDoc, TPrintDC::SetAbortProc, TPrintDC::Escape 


Bandinfo 

int BandInfo(TBandInfo& bandInfo); 

Retrieves information about the banding capabilities of this device, and copies it to the 
given bandInjo structure. Returns 1 if the call is successful; returns 0 if the call fails or if 
this device does not support banding. 


Seealso TBandInfo, TPrintDC::Escape 


DeviceCapabilities 

Static uint832 DeviceCapabilities(const char far* driver, const char far* device, const char far* port, int capability, 
char far* output=0, LPDEVMODE devmode=0); 

Retrieves data about the specified capability of the named printer driver, device, and port, 

and places the results in the output char array. The driver, device, and port names must 

be zero-terminated strings. The devmode argument points to a DEVMODE struct. If 
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devmode is 0 (the default), DeviceCapabilities retrieves the current default initialization 
values for the specified printer driver; otherwise, it retrieves the values contained in the 
DEVMODE structure. The format of the output array depends on the capability being 
queried. If output is 0 (the default), DeviceCapabilities returns the number of bytes 
required in the output array. Possible values for capability are as follows: 


Value 
DC_BINNAMES 


DC_BINS 


DC_DRIVER 
DC_DUPLEX 


DC_ENUMRESOLUTIONS 


DC_EXTRA 


Meaning 


The function enumerates the paper bins on the given device. Ifa device 
driver supports this constant, the output array is a data structure that 
contains two members. The first member is an array identifying valid paper 
bins: 
If a device driver supports this constant, the output array is a data structure 
that contains two members. The first member is an array identifying valid 
paper bins: 

short BinList [cBinMax] 
The second member is an array of character strings specifying the bin 
names: 


char PaperNames [cBinMax] [cchBinName] | 
If a device driver does not support this value, the output array is empty and 
the return value is NULL. 


If output is NULL, the return value specifies the number of bins supported. 


The function retrieves a list of constants that identify the available bins and 
copies the list to the output array. 


If this array is NULL, the function returns the number of supported bins. 
The following bin identifiers can be returned: 


DMBIN_AUTO 
DMBIN_CASSETTE 
DMBIN_ENVELOPE 
DMBIN_ENVMANUAL 
DMBIN_FIRST 
DMBIN_LARGECAPACITY 
DMBIN_LARGEFMT 
DMBIN_LAST 
DMBIN_LOWER 
DMBIN_MANUAL 
DMBIN_MIDDLE 
DMBIN_ONLYONE 
DMBIN_SMALLFMT 
DMBIN_TRACTOR 
DMBIN_UPPER 

The function returns the driver version number. 


The function returns the level of duplex support. The return value is 1 if the 
function supports duplex output; otherwise it is 0. 


The function copies a list of available printer resolutions to the output array. 
The resolutions are copied as pairs of int32 integers; the first value of the 
pair specifies the horizontal resolution and the second value specifies the 
vertical resolution. If output is 0, the function returns the number of 
supported resolutions. 


The function returns the number of bytes required for the device-specific 
data that is appended to the DEVMODE structure. 
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DC_FIELDS 


DC_FILEDEPENDENCIES 
DC_MAXEXTENT 


DC_MINEXTENT 


DC_ORIENTATION 


DC_PAPERNAMES 
DC_PAPERS 


DC_PAPERSIZE 


DC_SIZE 


The function returns a value indicating which members of the DEVMODE 
structure are set by the device driver. This value can be one or more of the 
following constants: 


DM_ORIENTATION 

DM_PAPERSIZE 

DM_PAPERLENGTH 

DM_PAPERWIDTH 

DM_SCALE 

DM_COPIES 

DM_DEFAULTSOURCE 

DM_PRINTQUALITY 

DM_COLOR 

DM_DUPLEX 

DM_YRESOLUTION 

DM_TTOPTION 
The function returns a list of files that must be loaded when the device 
driver is installed. If output is 0 and this value is specified, the function 


returns the number of file names that must be loaded. If output is nonzero, 
the function returns the specified number of 64-character file names. 


The function returns the maximum supported paper-size. These 
dimensions are returned in a POINT structure; the x member gives the 
maximum paper width and the y member gives the maximum paper 


length. 


The function returns the minimum supported paper-size. These 
dimensions are returned in a POINT structure; the x member gives the 


~ minimum paper width and the y member gives the minimum paper length. 


This function returns the number of degrees that a portrait-oriented paper 
is rotated counterclockwise to produce landscape orientation. if the return 
value is 0, there is no landscape orientation. If the return value is 90, the 

portrait-oriented paper is rotated 90 degrees (as is the case when HP laser 


_ printers are used). if the return value is 270, the portrait-oriented paper is 


rotated 270 degrees (as is the case when dot-matrix printers are used). 


This function returns a list of supported paper names such as Letter size or 
Legal size. The output array points to an array containing the paper names. 
If the output array is 0, the function returns the number of available paper 
sizes. 


The function retrieves a list of supported paper sizes and copies it to the 
output array. The function returns the number of sizes identified in the 
array. If output is 0, the function returns the number of supported paper 
siZes. 


The function retrieves the supported paper sizes (specified in .1 millimeter 


units) and copies them to the output array. 


The function returns the size of the DEVMODE structure required eye the 
given device driver. 
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Value _ | _ Meaning = ee | ; 
DC_TRUETYPE This fanciciy returns the eee pea S “5 TrueType font capabilities The 
values returned can be one or more of the following constants: 
DCTT_BITMAP Device supports printing TrueType fonts as 


graphics. 

(Dot-matrix and PCL printers) 
DCTT_DOWNLOAD Device supports downloading TryeType fonts. 

(PostScript and PCL printers) 


DCTT_SUBDEV Device supports substituting device fonts for 
TrueType fonts. 
(PostScript printers) 
DC_VERSION The function returns the device driver version number. 


If DeviceCapabilities succeeds, the return value depends on the value of capability, as 
noted above. Otherwise, the return value is GDI_ERROR. 


Seealso TDC::GetDeviceCaps, DEVMODE struct 


EndDoc 

int EndDoc(); 

Ends the current print job on this printer. EndDoc should be called immediately after a 
successfully completed print job. TPrintDC::AbortDoc should be used to terminate a 
print job because of error or user intervention. 


If successful, EndDoc returns a positive or zero value; otherwise a negative value is 
returned. 


Seealso 9 TPrintDC::StartDoc, TPrintDC::AbortDoc, TPrintDC::Escape 


EndPage 

int EndPage(); | 

Tells this printer's device driver that the application has finished writing to a page. If 
_ successful, EndPage returns a positive or zero value; otherwise a negative value is 
returned. Possible failure values are listed below: 


sp "ERROR a | Genel error, 

SP_APPABORT Job terminated because the application's print-canceling function returned 0. 
SP_USERABORT ‘User terminated the job. 

SP_OUTOFDISK Insufficient disk space for spooling. 


SP_OUTOFMEMORY Insufficient memory for spooling. 


Seealso TPrintDC::StartPage, TPrintDC::Escape 


Escape 

int Escape(int escape, int count=0, const void* inData=0, void* outData=0); 

Allows applications to access the capabilities of a particular device that are not directly 
available through the GDI of this DC. The Escape call is specified by setting a mnemonic 
value in the escape argument. In Win32 the use of Escape with certain escape values has 
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been replaced by specific functions. The names of these new functions are based on the — 
corresponding escape mnemonic, as shown in the following table: 


BANDINFO 


BEGIN_PATH 
CLIP_TO_PATH 
DEVICEDATA — 


DRAFTMODE 


DRAWPATTERNRECT 
ENABLEDUPLEX 


ENABLEPAIRKERNING 
ENABLERELATIVEWIDTHS 
ENDDOC 

END_PATH 
ENUMPAPERBINS 


ENUMPAPERMETRICS 
EPSPRINTING 
EXT_DEVICE_CAPS 


EXTTEXTOUT 


FLUSHOUTPUT | 
GETCOLORTABLE | 
GETEXTENDEDTEXTMETRICS 


_ GETEXTENTTABLE 
GETFACENAME 


GETPAIRKERNTABLE 
GETPHYSPAGESIZE 


_GETPRINTINGOFFSET 


~ GETSCALINGEFACTOR 
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Supersede oy PrintDC_. 


Obsolete in Win32. Because all printer drivers for Windows version 3.1 
and later set the text flag in every band, this escape is useful only for 
older printer drivers. 


No changes for Win32. This escape is specific to PostScript printers. 
No changes for Win32. This escape is specific to PostScript printers. 


Superseded in Win32. Applications should use the PASSTHROUGH 


escape to achieve the same functionality. 


Superseded in Win32. Applications can achieve the s same functionality 
by setting the dmPrintQuality member of the DEVMODE structure to 
DMRES_DRAFT and passing this structure to the CreateDC function. 


No changes for Win32. 


Superseded in Win32. Applications can achieve the same functionality 
by setting the dmDuplex member of the DEVMODE structure and 
passing this structure to the CreateDC function. 


No changes for Win32. 

No changes for Win32. 

Superseded by TPrintDC_EndDoc in Win32. 

No changes for Win32. This escape is specific to PostScript printers. 


Superseded in Win32. Applications can use 
TPrintDC::DeviceCapabilities to achieve the same functionality. 


Superseded in Win32. Applications can use 
TPrintDC::DeviceCapabilities to achieve the same functionality. 


No changes for Win32. This escape is specific to PostScript printers. 


Superseded in Win32. Applications can use TDC::GetDeviceCaps to 
achieve the same functionality. This escape is specific to PostScript 
printers. 


_ Superseded in Win32. Applications can use TDC: -ExtTextOut to 


achieve the same functionality. This escape is not supported by the 
version 3.1 PCL driver. 


Removed for Win32. 
Removed for Win32. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. © 


Superseded in Win32. Applications can use ::GetCharWidth to achieve 
the same functionality. This escape is not supported by the version 3.1 


PCL or PostScript drivers. 


No changes for Win32. This escape is specific to PostScript printers.. 
No changes for Win32. | | 


No changes for Win32. Support for this escape might change in future 
versions of Windows. 


No changes for Win32. Support for this escape might ee in future 
versions of Windows. 


No changes for Win32. Support for this escape might change in future 


versions of Windows. 


GETSETPAPERBINS | 


GETSETPAPERMETRICS 


GETSETPAPERORIENT 


GETSETSCREENPARAMS 
GETTECHNOLOGY 


GETTRACKKERNTABLE 
GETVECTORBRUSHSIZE 
GETVECTORPENSIZE 
MFCOMMENT 
NEWFRAME 
NEXTBAND 


PASSTHROUGH 
QUERYESCAPESUPPORT 
RESTORE _CTM 
SAVE_CIM 
SELECTPAPERSOURCE 


SETABORTPROC 
SETALLJUSTVALUES 


SET_ARC_ DIRECTION 
SET_BACKGROUND_COLOR 


SET_BOUNDS 
SETCOLORTABLE 


SETCOPYCOUNT 
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Action | ee | 
| Superseded in Win32. Applications can achieve the same functionality 


by calling TPrintDC::DeviceCapabilities to find the number of paper 
bins, calling ::ExtDeviceMode to find the current bin, and then setting 
the dmDefaultSource member of the DEVMODE structure and passing 
this structure to the CreateDC function. GETSETPAPERBINS changes 
the paper bin only for the current device context. A new device context 
will use the system-default paper bin until the bin is explicitly changed 
for that device context. 


Obsolete in Win32. Applications can use TPrintDC::DeviceCapabilities 
and ::ExtDeviceMode to achieve the same functionality. 


Obsolete in Win32. Applications can achieve the same functionality by 
setting the dmOrientation member of the DEVMODE structure and 
passing this structure to the CreateDC function. This escape is not 
supported by the Windows 3.1 PCL driver. 


No changes for Win32. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. This escape is not supported by the Windows 
3.1 PCL driver. 


No changes for Win32. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. 

No changes for Win32. Support for this escape might change in future 
versions of Windows. 

No changes for Win32. 


No changes for Win32. Applications should use ::StartPage and 
::EndPage instead of this escape. Support for this escape might change 
in future versions of Windows. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. 


No changes for Win32. 
No changes for Win32. 
No changes for Win32. This escape is specific to PostScript printers. 
No changes for Win32. This escape is specific to PostScript printers. 


Obsolete in Win32. Applications can achieve the same functionality by 
using TPrintDC::DeviceCapabilities. 


Superseded in Win32 by ::SetAbortProc. See TPrintDC::SetAbortProc. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. This escape is not supported by the Windows 
3.1 PCL driver. 


No changes for Win32. This escape is specific to PostScript printers. 


No changes for Win32. Applications should use ::SetBkColor instead of 
this escape. Support for this escape might change in future versions of 
Windows. 


No changes for Win32. This escape is specific to PostScript printers. 


No changes for Win32. Support for this escape might change in future 
versions of Windows. 


Superseded in Win32. An application should call 
TPrintDC::DeviceCapabilities, specifying DC_COPIES for the capability 
parameter, to find the maximum number of copies the device can 
make. Then the application can set the number of copies by passing to 
the CreateDC function a pointer to the DEVMODE structure. 
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SETKERNTRACK » No changes for Win32. 7 ies 

SETLINECAP » No changes for Win32. This escape is specific to PostScript printers. 

SETLINEJOIN No changes for Win32. This escape is specific to PostScript printers. 

SETMITERLIMIT ‘No changes for Win32. This escape is specific to PostScript printers. 
_SET_POLY_MODE No changes for Win32. This escape is specific to PostScript printers. 

SET_SCREEN_ANGLE | No changes for Win32. 

SET_SPREAD | No changes for Win32. 

STARTDOC Superseded in Win32. Applications should call ::StartDoc instead of 

this escape. 
TRANSFORM_CTM ~ Nochanges for Win32. This escape is eneidie to PostScript printers. 


Escape calls are translated and sent to the printer device driver. The inData buffer lets 
you supply any data needed for the escape. You must set count to the size (in bytes) of 
the inData buffer. If no input data is required, inData and count should be set to the 
default value of 0. Similarly, you must supply an outData buffer for those Escape calls 
that retrieve data. If the escape does not supply output, set outData to the default value 
of 0. 


NextBand 

int NextBand(TRect& rect); 

Tells this printer's device driver that the application has finished writing to a band. The 
device driver sends the completed band to the Print Manager and copies the coordinates 
of the next band in the rectangle specified by rect. : 


If successful, NextBand returns a positive or zero value; otherwise a negative value is 
returned. Possible failure values are listed below: 


SP_ERROR General error. 

SP_APPABORT Job terminated because the applection s print-canceling function returned 0. 
SP_USERABORT User terminated the job. 

SP_OUTOFDISK Insufficient disk space for spooling. 


SP_OUTOFMEMORY Insufficient memory for spooling. 


— Seealso TPrintDC::Escape, TPrintDC::BandInfo 


QueryAbort 

bool QueryAbort(int rsvd=0); 

16-bit applications only. Tries to call the AbortProc callback function for this printer to 

determine if a print job should be aborted or not. QueryAbort returns the value returned 

by AbortProc or true if no such callback function exists. true indicates that printing __ 
_ should continue; false indicates that the print job should be terminated. The rsvd 

argument is a reserved value that should be set to 0. 


Seealso TPrintDC::SetAbortProc, TPrintDC::AbortDoc 


QueryEscSupport 
uint QueryEscSupport(int escapeNum); 
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Returns true if the escape specified by escapeNum is implemented on this device; 
otherwise false. 


Seealso TPrintDC::Escape 


SetAbortProc 

int SetAbortProc(ABORTPROC proc); 

Establishes the user-defined proc as the printer-abort function for this printer. This 
function is called by TPrintDC::AbortDoc to cancel a print job during spooling. 


SetAbortProc returns a positive (nonzero) value if successful; otherwise it returns a 
negative (nonzero) value. 


Seealso TPrintDC::Escape 


SetCopyCount 

int SetCopyCount(int reqestCount, int& actualCount); 

Sets requestCount to the number of uncollated copies of each page that this printer 
should print. The actual number of copies to be printed is copied to actualCount. The 
actual count will be less than the requested count if the latter exceeds the maximum 
allowed for this device. SetCopyCount returns 1 if successful; otherwise, it returns 0. 


Seealso T'PrintDC::DeviceCapabilities, TPrintDC::Escape 


StartDoc 

int StartDoc(const char far* docName, const char far* output); | 
Starts a print job for the named document on this printer DC. If successful, StartDoc 
returns a positive value, the job ID for the document. If the call fails, the value 
SP_ERROR is returned. Detailed error information can be obtained by calling 
GetLastError. 


This function replaces the earlier ::Escape call with value STARTDOC. 
Seealso TPrintDC::EndDoc, TPrintDC::Escape 


StartPage 

int StartPage(); 

Prepares this device to accept data. The system disables ::ResetDC between calls to 
StartPage and EndPage, so that applications cannot change the device mode except at 
page boundaries. If successful, StartPage returns a positive value; otherwise, a negative 
or zero value is returned. 


Seealso TPrintDC::EndPage 


Protected data member 


Docinfo 

DOCINFO Doclnfo; 

Holds the input and output file names used by TPrintDC::StartDoc. The DOCINFO 
structure is defined as follows: 


typedef struct { | 
int cbSize; // size of the structure, bytes 
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DocInfo lpszDocName; // document name <= 32 chars inc. final 0 
DocInfo lpszOutput; // output file name 
} DOCINFO; | 


The [pszOutput field allows a print job to be redirected to a file. If this field is NULL, the 
output will go to the device for the specified DC. 


See also TPrintDC::StartDoc 


TPrintDialog::TData struct | printdia.h 


TPrintDialog::TData contains information required to initialize the printer dialog box 
with the user's print selections. This information consists of the number of copies to be 
_ printed, the first and last pages to print, the maximum and minimum number of pages 
that can be printed and various flag values that indicate whether the Pages radio button 
is displayed, the Print to File check box is enabled, and so on. TPrintDialog uses this 
struct to initialize the print dialog box. Whenever the user changes the print 
requirements, this struct is updated. 


If an error occurs, TPrintDialog::TData returns one of the common dialog ended error 
codes. T’PrintDialog::TData also takes care of locking and unlocking memory associated 
with the DEVMODE and DEVNAMES structures, which contain information about the 
printer driver, the printer, and the output printer port. 


TPrinter has access to this information through its data member, Data. 


Seealso T'PrintDialog, TPrinter 


Public data members 


Copies 
int Copies; 
Copies indicates the actual number of pages to be printed. 


Error 

—uint32 Error; 
If the dialog box is successfully executed, Error returns 0. Otherwise, it contains one of 
the following error codes. 


: ailed to create a dialog box. 
CDERR_FINDRESFAILURE Failed to find a specified resource. 
CDERR_INITIALIZATION Failed to initialize the common dialog box function. 
A lack of sufficient memory can generate this error. 
CDERR_LOCKRESOURCEFAILURE Failed to lock a specified resource. 


CDERR_LOADRESFAILURE Failed to load a specified resource. 

CDERR_LOADSTRFAILURE Failed to load a specified string. 

CDERR_MEMALLOCFAILURE ~ ~—_—_— Unable to allocate memory for internal data 
: structures. 
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CDERR_MEMLOCKFAILURE 


CDERR_REGISTERMSGFAIL 


PDERR_CREATEICFAILURE 


PDERR_DEFAULTDIFFERENT 


PDERR_DNDMMISMATCH 
PDERR_GETDEVMODEFFAIL 


PDERR_INITFAILURE 
PDERR_LOADDRVFAILURE 


PDERR_NODEFAULTPRN 
PDERR_NODEVICES 
PDERR_PARSEFAILURE 


PDERR_PRINTERNOTFOUND 


PDERR_RETDEFFAILURE 
PDERR_SETUPFAILURE 


Flags 
uint32 Flags; 
Flags, which are used to initialize the printer dialog box, can be one or more of the 
following values that control the appearance and functionality of the dialog box: 


D_ALLPAGES 
PD_COLLATE 


PD_DISABLEPRINTTOFILE 
PD_HIDEPRINTTOFILE 
PD_NOPAGENUMS 


PD_NOSELECTION 
PD_NOWARNING 


PD_PAGENUMS 


PD_PRINTSETUP 


PD_PRINTTOFILE 


TPrintDialog::TData struct 


Unable to lock the memory associated with a handle. 


A message, designed for the purpose of 
communicating between two applications, could not 
be registered. 


TPrintDialog failed to create an information context. 


The printer described by structure members doesn't 
match the default printer. This error message can 
occur if the user changes the printer specified in the 
control panel. 


The printer specified in DevMode and in DevNames is 
different. 


The printer device-driver failed to initialize the 
DevMode structure. 


The TPrintDialog structure could not be initialized. 


The specified printer's device driver could not be 
loaded. 


A default printer could not be identified. 
No printer drivers exist. 


The string in the [devices] section of the WIN.INI file 
could not be parsed. 


The [devices] section of the WIN.INI file doesn't 
contain the specified printer. 


Either DevMode or DevNames contain zero. 
TPrintDialog failed to load the required resources. 


closed the dialog box. 


Causes the Collate checkbox to be checked when the dialog 
box is created. 


Disables the Print to File check box. 
Hides and disables the Print to File check box. 


Disables the Pages radio button and the associated edit 
control. 


Disables the Selection radio button. 


Prevents the warning message from being displayed when 
there is no default printer. 


Selects the Pages radio button when the 

dialog box is created. | 

Displays the Print Setup dialog box rather than the Print dialog 
box. 


Checks the Print to File check box when the dialog box is 
created. 
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TPrintDialog::TData struct 


PD_RETURNDC Returns a device context matching the selections that the user 
, made in the dialog box. 
PD_RETURNDEFAULT Returns DevNames structures that are initialized for the default 
. printer without displaying a dialog box. 

PD_RETURNIC Returns an information context matching the selections that | 
the user made in the dialog box. | 

PD_SELECTION Selects the Selection radio button when the dialog box is 
created. 

PD_SHOWHELP | Shows the Help button in the dialog box. 


PD_USEDEVMODECOPIES _ Ifa printer driver supports multiple copies, setting this flag 
causes the requested number of copies to be stored in the 
dmCopies member of the DevMode structure and 1 in Copies. If a 
printer driver does not support multiple copies, setting this 
flag disables the Copies edit control. If this flag is not set, the 
number 1 is stored in DevMode and the requested number of 
copies in Copies. 


FromPage 
int FromPage; 
FromPage indicates the beginning page to print. 


Seealso TPrintDialog::TData::ToPage 


MaxPage 
int MaxPage; 
MaxPage indicates the maximum number of pages that can be printed. 


MinPage 
int MinPage; 
_ MinPage indicates the minimum sume of pages that can be printed. 


_ ToPage 
int ToPage; 
ToPage indicates the ending page to print. 


Seealso TPrintDialog::TData::FromPage 


Public member functions 


ClearDevMode 
void ClearDevMode(); 
Clears device mode information (information necessary to initialize the dialog senaeisy 


ClearDevNames 

void ClearDevNames(); 
Clears the device name information (information that contains three strings used to 
specify the driver name, the printer name, and the output port name). 


GetDeviceName — : 
const char far* GetDeviceName() const; 
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Gets the name of the output device. 


GetDevMode 

const DEVMODE far* GetDevMode() const; 

Gets a pointer toa DEVMODE structure (a structure containing information necessary 
to initialize the dialog controls). 


GetDevNames 

~ const DEVNAMES far* GetDevNames() const; 
Gets a pointer toa DEVNAMES structure (a structure containing three strings used to 
specify the driver name, the printer name, and the output port name). 


GetDriverName 
const char far* GetDriverName() const; 
Gets the name of the printer device driver. 


GetOutputName 
const char far* GetOutputName() const; 
Gets the name of the physical output medium. 


Lock 
void Lock(); 
Locks memory associated with the DEVMODE and DEVNAMES structures. 


SetDevMode 
void SetDevMode(const DEVMODE far* devMode); 
Sets the values for the DEVMODE structure. 


SetDevNames 
void SetDevNames(const char far* driver, const char far* device, const char far* output); 
Sets the values for the DEVNAMES structure. 


TransferDC 
TPrintDC* TransferDC(); 
Creates and returns a TPrintDC with the current settings. 


Unlock 
void Unlock(); ! 
Unlocks memory associated with the DEVMODE and DEVNAMES structures. 


TPrintDialog class printdia.h 


TPrintDialog displays either a modal print or a print setup dialog box. The print dialog 
box lets you specify the characteristics of a particular print job. The setup dialog box lets 
you configure the printer and specify additional print job characteristics. You can also 
use TPrinter and TPrintout to provide support for printer dialog boxes. TPrintDialog uses 
the TPrintDialog::TData struct to initialize the dialog box with the user's printe: options, 
such as the number of pages to print, the output device, and so on. 
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See also 
- TPrintDialog: ‘TData struct, TPrinter, TPrintout 


Public constructor _ 


errr arm eerererentcenanan tee te a eT EPH Sr ATU VER ere rf 


Constructor 
TPrintDialog(TWindow* parent, TData& data, const char far* printTfemplateName=0, 

const char far* setupTemplateName=0, const char far* title=0, TModule* module=0); 
Constructs a print or print setup dialog box with specified data from the 
TPrintDialog::TData structure, parent window, window caption, print and setup — 
templates, and module. 


Seealso TPrintDialog::TData struct 


Public member functions 


DoExecute 

int DoExecute(); 

If no error occurs, DoExecute copies flags and print specifications into the data argument 
in the constructor. If an error occurs, DoExecute sets the error number of data to an error 
code from TPrintDialog::TData::Error . 


Seealso TPrintDialog::TData::Error 


GetDefaultPrinter 

bool GetDefaultPrinter(); 

Without displaying a dialog box, GetDefaultPrinter gets the device mode and name that 
are initialized for the system default printer. 


Protected data members 


Data 
TData& Data; 
Data is a reference to the TData object passed in the constructor. The TData object 
_ contains print specifications such as the number of copies to be printed, the number of 
pages, the ouput device name, and so on. | 


Seealso TPrintDialog::TData struct 
pd 
PRINTDLG pd; 


Specifies the dialog box print job characteristics such as page range, number of copies, 
device context, and so on necessary to initialize the print or print setup dialog box. 


See also TPrintDialog: ‘T’Data struct 
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Protected member functions 


CmSetup 
void CmSetup(); 
Responds to the click of the setup button with an EV_COMMAND message. 


DialogFunction 
bool DialogFunction(uint message, WPARAM, LPARAM); 
Returns true if a message is handled. 


Seealso TDialog::DialogFunction 


Response table entries 


The TPrintDialog response table has no entries. 


TPrinter class printer.h 


TPrinter represents the physical printer device. To print or configure a printer, initialize 
an instance of T’Printer. 


Public constructor and destructor 


Constructor 

TPrinter(); 

Constructs an instance of TPrinter associated with the default printer. To change the 
printer, call SetDevice after the object has been initialized or call Setup to let the user 
select the new device through a dialog box. 


Destructor 
virtual ~TPrinter(); 
Frees the resources allocated to TPrinter. 


Public member functions 


ClearDevice 

virtual void ClearDevice(); 

Called by SetPrinter and the Destructor, ClearDevice disassociates the device with the 
current printer. ClearDevice changes the current status of the printer to 
PF_UNASSOCIATED, which causes the object to ignore all calls to Print until the object 
is reassociated with a printer. 


GetSetup 
TPrintDialog::TData& GetSetup(); 
Returns a reference to the TPrintDialog data structure. 
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GetUserAbort 
~ gtatic bool GetUserAbort(); 
Returns true if the user has chosen to stop printing through the printing dialog. Returns | 
_ false otherwise. 


. 


Print 

virtual bool Print(TWindow* parent, TPrintout& printout, bool prompt); 
Print renders the given printout object on the associated printer device and displays an 
Abort dialog box while printing. It displays any errors encountered during printing. 
Prompt allows you to show the user a window. 


See also TPrinter::Error 


ReportError © 

virtual void ReportError(TWindow* parent, TPrintout& printout); 

Print calls ReportError if it encounters an error. By default, it brings up the system 
message box with an error string created from the default string table. This function can 
be overridden to show a custom error dialog box. 


Setup 

virtual void Setup(TWindow* parent); 

Setup lets the user select and/or configure the currently associated printer. Setup opens 
a dialog box as a child of the given window. The user then selects one of the buttons in 

the dialog box to select or configure the printer. The form of the dialog box is based on 

TPrintDialog, the common dialog printer class. | 


SetUserAbort 
static void SetUserAbort(bool abort=true); 
Sets the printing abort flag. 


Protected data members 


_ BandRect 

_ TRect BandRect; 
BandRect specifies the size of the banding rectangle. 
Data 
TPrintDialog::TData* Data; 


Data is a pointer to the TPrintDialog data structure that contains information about the 
user's print selection. 


Seealso TPrintDialog::TData struct | 


Error 

int Error; 
Error is the error code returned by GDI during printing. This value is initialized duringa _ 
call to Print. . 


FirstBand 
bool FirstBand; 
FirstBand is set to true if the first band of the print job i is ae printed, otherwise false. 
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Flags 
unsigned Flags; 
The Flags data member specifies whether the printout bands contain graphics bands, 
text bands, or both. The valid flag values are enumerated by TPrintoutFlags: 
enum TPrintoutFlags { 
pfGraphics // Current band accepts graphics 
pfText // Current band accepts text 
pfBoth // Current band accepts either graphics or text 
ay 


PageSize 
TSize PageSize; 
PageSize specifies the size of the printed page, as specifed in se device context. 


UseBandinfo 
bool UseBandinto; 
UseBandInfo is set to true if the sani supports banding, otherwise it's set to false. 


Protected member functions 


CalcBandingFlags 

void CalcBandingFlags(TPrintDC& prnDC); 

CalcBandingFlags determines if there are either text and graphics bands, and sets data 
member Flags accordingly. 


CreateAbortWindow 
virtual TWindow* CreateAbortWindow(TWindow* parent, TPrintout& printout); 
Creates a printer abort dialog message box. 


ExecPrintDialog 
virtual bool ExecPrintDialog(TWindow* parent); 
Executes a TPrintDialog. 


GetDefaultPrinter 
virtual void GetDefaultPrinter(); 
Updates the printer structure with information about the user's default printer. 


SetPrinter 

virtual void SetPrinter(const char* driver, const char* device, const char* output); 

SetPrinter changes the printer device association. Setup calls SetPrinter to change the 
association interactively. The valid parameters to this method can be found in the 
[devices] section of the WIN.INI file. 


Entries in the [devices] section have the following format: 


<device name>=<driver>, <port> {, <port>} 
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TPrinter: :TXPrinter class a 7 printer.h 


A nested class, TXPrinter describes an exception that results from an invalid printer 
object. This type of error can occur when printing to the physical printer. 


Public constructors 


Constructors | 
TXPrinter(uint resid = IDS_PRINTERERROR); 
Constructs a TXPrinter object with a default IDS_PRINTERERROR ae 


TPrinterAbortDig class | printer.h 


TPrinterAbortDlg is the object type of the default printer-abort dialog box. This dialog 
box is initialized to display the title of the current printout, as well as the device and port 
currently used for printing. 


TPrinterAbortDlg expects to have three static text controls, with control IDs of 101 for the 
title, 102 for the device, and 103 for the port. These controls must have "%s" somewhere 
in the text strings so that they can be replaced by the title, device, and port. The dialog- 
box controls can be in any position and tab order. 


Public constructor 


Constructor 
TPrinterAbortDig(TWindow* parent, TResld resid, const char far’ title, 
const char far* device, const char far* port); 
Constructs an Abort dialog box that contains a Cancel button and displays the given 
title, device, and port. | 


Protected member functions 


EvCommand 
virtual LRESULT EvCommand(uint id, HWND hWndCt, uint notifyCode); 
Handles the Cancel button on the Printer-abort dialog box. 


SetupWindow 

void SetupWindow(); 

Associates objects with the dialog resource template so that the title, device, and port 
can be determined for printing. See the description of TPrintoutFlags for information 
about printing flags and printer status information. 


See also TPrintoutFlags enum 
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TPrintout class | printer.h 


TPrintout represents the physical printed document that is to sent to a printer to be 
printed. TPrintout does the rendering of the document onto the printer. Because this 
object type is abstract, it cannot be used to print anything by itself. For every document, 
or document type, a class derived from TPrintout must be created and its PrintPage 
function must be overridden. 


Public constructor and destructor 


Constructor 
TPrintout(const char far* title); 
Constructs an instance of T’PrintOut with the given ttle. 


Destructor 
virtual ~TPrintout(); 
Destroys the resources allocated by the constructor. 


Public member functions 


BeginDocument 

virtual void BeginDocument(int startPage, int endPage, unsigned flags); 

The printer object's Print function calls BeginDocument once before printing each copy of 
a document. The flags field indicates if the current print band accepts graphics, text, or 
both. 


The default BeginDocument does nothing. Derived objects can override BeginDocument to 
perform any initialization needed at the beginning of each copy of the document. 


Seealso TPrintoutFlags enum 


BeginPrinting 

virtual void BeginPrinting(); 

The printer object's Print function calls BeginPrinting once at the beginning of a print job, 
regardless of how many copies of the document are to be printed. Derived objects can 
override BeginPrinting to perform any initialization needed before printing. 


EndDocument 

virtual void EndDocument(); 

The printer object's Print function calls EndDocument after each copy of the document 
finishes printing. Derived objects can override EndDocument to perform any needed 
actions at the end of each document. 


EndPrinting 

virtual void EndPrinting(); 

The printer object's Print function calls EndPrinting after all copies of the document 
finish printing. Derived objects can override EndPrinting to perform any needed actions 
at the end of each document. 
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| GetDialoginfo | | | 
virtual void GetDialogIinfo(int& minPage, int& maibane. int& selFromPage, int& selToPage): 
Retrieves information needed to allow the printing of selected pages of the document 
and returns true if page selection is possible. Use of page ranges is optional, but if the 
page count is easy to determine, GetDialogInfo sets the number of pages in the 
document. Otherwise, it sets the number of pages to 0 and printing will continue until 
HasPage returns false. 


GetTitle 
const char far* GetTitle() const; 
Returns the title of the current prods 


HasPage 

virtual bool HasPage(int pageNumber); 

HasPage is called after every page is printed. By default, it returns false, indicating that 
only one page is to be printed. If the document contains more than one page, this 
function must be overridden to return true while there are more pages to print. 


PrintPage 
virtual void PrintPage(int page, TRect& rect, unsigned flags); 
PrintPage is called for every page (or band, if Banding is true) and must be svenidden to 
print the contents of the given page. The rect and flags parameters are used during 
banding to indicate the extent and type of band currently requested from the driver 

_ (and should be ignored if Banding is false). page is the number of the current page. 


SetPrintParams 

virtual void SetPrintParams(TPrintDC* dc, TSize sacosiel 

SetPrintParams sets DC to dc and PageSize to pageSize. The printer object's Print function 
calls SetPrintParams to obtain the information it needs to determine pagination and page 
count. Derived objects that override SetPrintParams must call the inherited function. 


Seealso ‘['PreviewPage::Paint 


WantBanding 
bool WantBanding() const; 
Returns the value of data member Banding. 


WantForceAllBands 
bool WantForceAllBands() const; 
Returns the value of data member Pore Apis: 


Type definitions — printer.h 


TPrintoutFlags enum 
enum{pfGraphics, pfText, pfBoth}; 


374 ObjectWindows Reference Guide 


TPrintPreviewDC class 


ObjectWindows defines the following banding constants used to set flags for printout 
objects. 


Mang eee 
Current band accepts only graphics. 


Current band accepts only text. 


Current band accepts both text and graphics. 


Seealso TPrinter, TPrintOut 


Protected data members 


Banding 

bool Banding; | 

If Banding is true, the printout is banded and the PrintPage function is called once for 
every band. Otherwise, PrintPage is called only once for every page. Banding a printout 
is more memory- and time-efficient than not banding. By default, Banding is set to false. 


DC 
TPrintDC* DC; 
DC is the handle to the device context to use for printing. 


ForceAllBands 

bool ForceAllBands; 

Many device drivers do not provide all printer bands if both text and graphics are not 
performed on the first band (which is typically a text-only band). Leaving ForceAllBands 
true forces the printer driver to provide all bands regardless of what calls are made in | 
the PrintPage function. If PrintPage does nothing but display text, it is more efficient for 
ForceAllBands to be false. By default, it is true. ForceAllBands takes effect only if Banding 
is true. 


PageSize 
TSize PageSize; 
PageSize is the size of the print area on the printout page. 


Title 
const char far* GetTitle() const; 
Returns the title of the current printout. 


TPrintPreviewDC class preview.h 


Derived from TPrintDC, TPrintPreviewDC maps printer device coordinates to logical 
screen coordinates. It sets the extent of the view window and determines the screen and 
printer font attributes. Many of TPrintPreviewDC’s functions override TDC’s virtual 
functions. : 
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Form 1 


Form 2 


Public constructor and destructor 


Constructor 

TPrintPreviewDC(TDC& screen, TPrintDC& printdc, const TRect& client, const TRect& clip); 
TPrintPreviewDC’'s constructor takes a screen DC as well as a printer DC. The screen DC 
is passed to the inherited constructor while the printer DC is copied to the member, 
PmDC. 


Destructor 
~TPrintPreviewDC(); 


Destroys a TPrintPreviewDC object. 


Public member functions 


GetDeviceCaps 

int GetDeviceCaps(int index) const; 

GetDeviceCaps returns capability information, such as font and pitch attributes, about the 
printer DC. The index argument specifies the type of information required. 


Seealso TDC::GetDeviceCaps 


_ LPtoSDP 


bool LPtoSDP(TPoint* points, int count = 1) const; 
Converts each of the count points in the points array from logical points of the printer DC 
to screen points. Returns a nonzero value if the call is successful; otherwise, returns 0. 


bool LPtoSDP(TRect& rect) const; 
Converts each of the points in the rect from logical points of the printer DC to screen 
device points. Returns a nonzero value if the call is successful; otherwise, returns 0. 


Seealso TPrintPreviewDC::SDPtoLP, TDC::LPtoDP 


OffsetViewportOrg 

bool OffsetViewportOrg(const TPoint& delta, TPoint far* oldOrg = 0); 

Modifies this DC's viewport origin relative to the current values. The delta x- and y- 
components are added to the previous origin and the resulting point becomes the new 
viewport origin. The previous origin is saved in oldOrg. Returns nonzero if the call is 
successful; otherwise, returns 0. 


Seealso TPrintPreviewDC::SetViewportOrg, TDC::OffsetViewportOrg 


ReOrg 
virtual void ReOrg(); 


_ Gets the x- and y- extents of the viewport, equalizes the logical and screen points, and 


resets the x- and y- extents of the viewport. 


ReScale 

virtual void ReScale(); 

Maps the points of the printer DC to the screen DC. Sets the screen window extent equal 
to the maximum logical pointer of the printer DC. 


376 ObjectWindows Reference Guide 


Form 1 


Form 2 


TPrintPreviewDC class 


RestoreFont 
void RestoreFont(); 
Restores the original GDI font object to this DC. 


Seealso TPrintPreviewDC::SelectObject, TDC::OrgFont 


ScaleViewportExt 

bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0); 

Modifies this DC's viewport extents relative to the current values. The new extents are 
derived as follows: 


xNewVE = (xO1GVE * xNum)/ xDenom 
yYNewVE = (yOldVE * yNum)/ yDenom 


The previous extents are saved in oldExtent. Returns nonzero if the call is successful; 
otherwise returns 0. 


Seealso TDC::ScaleViewportExt, TPrintPreviewDC::SetViewportExt 


ScaleWindowExt 

bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0); 

Modifies this DC's window extents relative to the current values. The new extents are 
derived as follows: 


xNewWE = (xOLdWE * xNum)/ xDenom 
yNewWE = (yOldWE * yNum)/ yDenom 


The previous extents are saved in oldExtent. Returns nonzero if the call is successful; 
otherwise returns 0. 


See also TDC::SetWindowExt, TPrintPreviewDC::ScaleWindowExt 


SDPtoLP 

bool SDPtoLP(TPoint* points, int count = 1) const; 

Converts each of the count points in the points array from screen device points to logical 
points of the printer DC. Returns a nonzero value if the call is successful; otherwise, 
returns 0. 


bool SDPtoLP(TRect& rect) const: 
Converts each of the points in the rect from screen device points to logical points of the 
printer DC. Returns a nonzero value if the call is successful; otherwise, returns 0. 


Seealso TPrintPreviewDC::LPtoSDP, TDC::DPtoLP 


SelectObject 
void SelectObject(const TFont& newFont); 
Selects the given font object into this DC. 


Seealso § T'PrintPreviewDC::SelectStockObject, TDC::SelectObject 
SelectStockObject 


void SelectStockObject(int index); 
Retrieves a handle to a predefined stock font. 


See also TDC::SelectStockObject 


Chapter 2, ObjectWindows library reference 377 


TPrintPreviewDC class 


- SetBkColor 
TColor SetBkColor(TColor color); 


Sets the current background color of this DC to the given color value or the nearest 
available. Returns 0x80000000 if the call fails. 


See also TDC::SetBkColor 


SetMapMode 
int SetMapMode(int mode); | | 
Sets the current window mapping mode of this DC to mode. Returns the previous 
_ mapping mode value. The mapping mode defines how logical coordinates are mapped 
to device coordinates. It also controls the orientation of the device's x- and y-axes. 


See also TDC::GetMapMode, TDC::SetMapMode 


SetTextColor 
TColor SetTextColor(TColor color); 


Sets the current text color of this DC to the given color value. The text color determines 
the color displayed by TDC::TextOut and TDC::ExtTextOut. 


See also TDC::GetTextColor, TDC::SetTextColor 


SetViewportExt | 

bool SetViewportExt(const TSize& extent, TSize far* oldExtent = 0); 

Sets the screen's viewport x- and y-extents to the given extent values. The previous 
extents are saved in oldExtent. Returns nonzero if the call is successful; otherwise, 
returns 0. The extent value determines the amount of stretching or compression needed 
in the logical coordinate system to fit the device coordinate system. extent also 
determines the relative orientation of the two coordinate systems. 


Seealso TDC::GetViewportExt, TDC::SetViewportExt 


_ SetViewportOrg 
bool OffsetViewportOrg(const TPoint& delta, TPoint far* oldOrg = 0); 
Modifies this DC's viewport origin relative to the current values. The delta x- and y- 
components are added to the previous origin and the resulting point becomes the new 
viewport origin. The previous origin is saved in oldOrg. Returns nonzero if the call is 
successful; otherwise, returns 0. 


Seealso TPrintPreviewDC::SetViewportOrg, TDC::OffsetViewportOrg 


SetWindowExt 

bool SetWindowExt(const TSize& extent, TSize far* oldExtent=0); 

Sets the DC's window x- and y-extents to the given extent values. The previous extents 
are saved in oldExtent. Returns nonzero if the call is successful; otherwise, returns 0. The 
extent value determines the amount of stretching or compression needed in the logical © 
coordinate system to fit the device coordinate system. extent also determines the relative 
orientation of the two coordinate systems. 


See also TDC::GetWindowExt, TDC::SetWindowExt, 
TPrintPreviewDC::ScaleWindowExt 
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SyncFont 
virtual void SyncFont(); 
Sets the screen font equal to the current printer font. 


Protected data members 


CurrentPreviewFont 
TFont* CurrentPreviewFont; 
The current view font. 


PrnDC 
TPrintDC& PrnDC; 
Holds a reference to the printer DC. 


PrnFont 
HFONT PrnFont; 
The current printer font. 


Protected member functions 


GetAttributeHDC 
HDC GetAttributeHDC() const; 
Returns the attributes of the printer DC (PrnDC). 


Seealso TDC::GetAttributeHDC 


TProfile class — | profile.h 


An instance of TProfile encapsulates a setting within a system file, often referred to as a 
profile or initialization file. Examples of this type of file include the Windows initialization 
files SYSTEM.INI and WIN.INI. Within the system file itself, the individual settings are 
grouped within sections. For example, 


[Diagnostics] ; section name 
Enabled=0 + setting 


For a setting, the value to the left of the equal sign is called the key. The value to the right 
of the equal sign, the value, can be either an integer or a string data type. 


Public constructor and destructor 


Constructor 

TProfile(const char* section, const char* filename=0); 

Constructs a TProfile object for the indicated section within the profile file specified by 
filename. If the file name is not provided, the file defaults to the system profile file; for 
example, WIN.INI under Windows. 
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Destructor 
~TProfile(); 
Destroys the TProfile opiec: 


Public member functions 


Getint 

int GetInt(const char* key, int defaultInt = 0); 

Looks up and returns the integer value associated with the given string, key. If key is not 
found, the default ane defaultInt, is returned. 


GetString 

bool GetString(const char* key,.char buffl], unsigned buffSize, const char* defaultString = m; 

Looks up and returns the string value associated with the given key string. The string 
value is copied into buff, up to buffSize bytes. If the key is not found, defaultString 
provides the default value. If a 0 key is passed, all section values are returned in buff. 


Writelnt 

bool Writelnt(const char* key, const char* int value); | 

Looks up the key and replaces its value with the integer value passed (int). If the key is 
not found, WriteInt makes a new entry. Returns true if successful. 


WriteString 

bool WriteString(const char* key, const char* str); 

Looks up the key and replaces its value with the string value eee (str). If the key is 
not found, WriteString makes a new entry. Returns true if successful. 


TPXPictureValidator objects compare user input with a picture of a data format to 
determine the validity of entered data. The pictures are compatible with the pictures 
Borland's Paradox relational database uses to control data entry. For a complete 
description of picture specifiers, see the Picture member function. 


Public constructor 


Constructor 

TPXPictureValidator(const char far* pic, bool autoFill=false); 

Constructs a picture validator object by first calling the constructor inherited from 
TValidator and setting pic to point to it. Then sets the voFill bit in Options if AutoFill is true 
and sets Options to voOnAppend. Throws a TX Validator exception if the picture is invalid. 


Public member functions 


Error 
void Error(); 
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Overrides TValidator’s virtual function and displays a message box that indicates an 
error in the picture format and displays the string pointed to by Pic. 


See also TValidator::Error 


IsValid 

bool IsValid(const char far* str); 

IsValid overrides TValidator’s virtual function and compares the string passed in str with 
the format picture specified in Pic. IsValid returns true if Pic is NULL or if Picture returns 
Complete for str, indicating that str needs no further input to meet the specified format; 
otherwise, it returns false. 


Seealso TPXPictureValidator::Picture 


IsValidinput 

bool IsValidinput(char far* str, bool suppressFill); 

IsValidInput overrides TValidator’s virtual function and checks the string passed in str 
against the format picture specified in Pic. IsValid returns true if Pic is NULL or Picture 
does not return Error for str; otherwise, it returns false. The suppressFill parameter 
overrides the value in voFill for the duration of the call to IsValidInput. 


If suppressFill is false and voFill is set, the call to Picture returns a filled string based on 
str, so the image in the edit control automatically reflects the format specified in Pic. 


Seealso TPXPictureValidator::Picture 


Picture 
virtual TPicResult Picture(char far* input, bool autoFill=false); 


Formats the string passed in input according to the format specified by the picture string 
pointed to by Pic. Picture returns prError if there is an error in the picture string or if input 
contains data that cannot fit the specified picture. Returns prComplete if input can fully 
satisfy the specified picture. Returns prIncomplete if input contains data that incompletely 
fits the specified picture. 


The following characters are used in creating format pictures: 


ear 7 : ree ane ‘ ae 
2 Accept only a letter 
(case_insensitive) 
& Accept only a letter, 
force to uppercase 
@ Accept any character 
Accept any character, 
force to uppercase 
Match : Take next character 
| literally 
: Repetition count 
[] Option 
{} Grouping operators 
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- Set of alternatives — 
All others Taken literally 


Seealso TPicResultenum 


Protected data member 


Pic 

string Pic; 

Points to a string containing the picture that specifies the format for data in the 
associated edit control. The constructor sets Pic to a string that is passed as one of the 
parameters. 


een class radiobut.h 


Form 1 


Form 2 


A TRadioButton is an interface object that represents a corresponding radio button 


element in Windows. Use TRadioButton to create a radio button control in a parent 
TWindow. A TRadioButton can also be used to facilitate communication between your 
application and the radio button controls of a TDialog. 


Radio buttons have two states: checked and unchecked. TRadioButton inherits its state 
management member functions from its base class, TCheckBox. Optionally, a radio 
button can be part of a group (TGroupBox) that visually and logically groups its controls. 
TRadioButton is a streamable class. 


Public constructors 


Constructors 
TRadioButton(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, TGroupBox *group = 

0, TModule* module = 0); 
Constructs a radio button object with the supplied parent window (parent), control ID 
(id), associated text (title), position (x, y) relative to the origin of the parent window's 
client area, width (w), height (i), and associated group box (group). Invokes the 
TCheckBox constructor with similar parameters. The style is set to WS_CHILD | 
WS_VISIBLE | BS_AUTORADIOBUTTON. 


TRadioButton(TWindow* parent,int resourceld, TGroupBox *group, TModule* module = 0); — 

Constructs a TRadioButton object to be associated with a radio button control of a_ 
TDialog. Invokes the TCheckBox constructor with identical parameters.The resourceld 
parameter must correspond to a radio button resource that you define. 


Seealso TControl::TControl 
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Protected member functions 


BNClicked 
void BNClicked(); 
Responds to an incoming BN_CLICKED message. 


See also BN_xxxx Button Message Constants 


GetClassName 
char far* GetClassName(); 
Returns "BUTTON," the name of the predefined radio button class. 


Response table entries 


EV_MESSAGE (BM SETSTYLE, B BMSetStyle) ~ BMSetStyle 


EV_WM_GETDLGCODE EvGetDlgCode 
TRangeValidator class validate.h 


A TRangeValidator object determines whether the data typed by a user falls within a 
designated range of integers. TRangeValidator is a streamable class. 


Public constructor 


Constructor 

TRangeValidator(long min, long max); 

Constructs a range validator object by first calling the constructor inherited from 
TFilterValidator, passing a set of characters containing the digits '0'..'9' and the characters 
'+' and '"—'. Sets Min to min and Max to max, establishing the range of acceptable long 
integer values. 


See also TFilterValidator::TFilterValidator 


Public member functions 


Error 

void Error(); 

Error overrides TValidator’s virtual function and displays a message box indicating that 
the entered value does not fall within the specified range. 


IsValid 
bool IsValid(const char far* str); 


Converts the string str into an integer number and returns true if the result meets all 
three of these conditions: 


e Itis a valid integer number. 
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° Its value is greater than or equal to min. 
¢ Its value is less than or equal to max. 


If any of those tests fails, IsValid returns false. 


Transfer 


_uint Transfer(char far* str, void* buffer, TTransferDirection direction); 


Incorporates the three types, tdSizeData, tdGetData, and tdSetData, that a range validator 


~ can handle for its associated edit control. str is the edit control's string value, and buffer is 


the data passed to the edit control. Depending on the value of direction, Transfer either 
sets str from the number in buffer or sets the number at buffer to the value of the string str. 
If direction is tdSetData, Transfer sets str from buffer. If direction is tdGetData, Transfer sets 
buffer from str. If direction is tdSizeData, Transfer neither sets nor reads data. 


Transfer always returns the size of the data transferred. 


Seealso TWindow::Transfer 


Protected data members 

Max 

long Max; 

Max is the highest valid long integer value for the edit control. 


long Min; | 
Min is the lowest valid long integer value for the edit control. 


TRegion class gdiobjec.h 


_ Form1 


ee sere a A ee eh ere 


TRegion, derived from TGdiobject, represents GDI abstract shapes or regions. TRegion can 
construct region objects with various shapes. Several operators are provided for 
combining and comparing regions. 


Type definitions 


TEllipse 

enum TEllipse{Ellipse}; 

Defines the class-specific constant, Ellipse, used to distinguish the ellipse constructor 
from the rectangle copy constructor. 


Seealso ‘l’Region::TRegion (constTRecté&rect), TRegion::TRegion 
(constTRect&ETEllipse) 


Public constructors 


Constructors 
TRegion(); 
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Form 2 


Form 3 


Form 4 


Form 5 


Form 6 


Form 7 


Form 8 


TRegion class 


The default constructor creates an empty TRegion object. Handle is set to 0 and 
ShouldDelete is set to true. 


TRegion(HRGN handle, TAutoDelete autoDelete = NoAutoDelete); | 

Creates a TRegion object sets the Handle data member to the given borrowed handle. The 
ShouldDelete data member defaults to false ensuring that the borrowed handle is not 
deleted when the C++ object is destroyed. HRGN is the data type representing the 
handle to an abstract shape. 


TRegion(const TRegion& region); 
This public copy constructor creates a copy of the given TRegion object as in 
TRegion myRegion = yourRegion; 


TRegion(const TRect& rect); 

Creates a region object from the given TRectangle object as in 
TRegion myRegion (rect) ; 
TRegion* pRegion; 
pRegion = new TRegion(rect2) ; 

TRegion(const TRect& E, TEllipse); 


Creates the elliptical TRegion object that inscribes the given rectangle E. The TEllipse 
argument distinguishes this constructor from the TRegion(const TRect& rect) constructor. 


TRegion(const TRect& rect, const TSize& corner); 
Creates a T’Region object from the given rect corner. 


TRegion(const TPoint* points, int count, int fillMode); 
Creates a filled TRegion object from the polygons given by points and fillMode. 


TRegion(const TPoint* points, const int* polyCounts, int count,int fillMode); 
Creates a filled TRegion object from the polygons given by points and fillMode. 


See also TGdiObject::Handle, TGdiObject::ShouldDelete, TPoint class, TRect class, 
TSize class 


Public member functions 


Contains 
bool Contains(const TPoint& point) const; 
Returns true if this region contains the given point. 


Seealso TPoint 


GetRgnBox 

int GetRgnBox(TRect& box) const; 

TRect GetRgnBox() const; 

Finds the bounding rectangle (the minimum rectangle containing this region). In Form 
1, the resulting rectangle is placed in box and the returned values are as follows: 


COMPLEXREGION Region has overlapping border 
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NULLREGION Region is empty. 
SIMPLEREGION Region has no overlapping borders. 


In Form 2, the resulting rectangle is returned. 
Seealso ‘Rect | 


operator == 
bool operator ==(const TRegion& other) const; 
Returns true if this region is equal to the other region. 


Seealso 'Region::operator!= 


operator != 
bool operator !=(const TRegion& other) const; 
Returns true if this region is not equal to the other region. 


Seealso Region::operator == 


operator = 

TRegion& operator =(const TRegion& source); 

Assigns the source region to this region. A reference to the result is returned, allowing 
_ chained assignments. 


operator += 

TRegion& operator +=(const TSize& delta); 

Adds the given delta to each point of this region to displace (translate) it by delta.x and 
delta.y. Returns a reference to the resulting region. 


Seealso TSize, TRegion::operator —= 


operator —= 

TRegion& operator —=(const TSize& delta); 

TRegion& operator —=(const TRegion& source); 

The first form subtracts the given delta from each point of this region to displace 
(translate) it by —delta.x and —delta.y. The second form creates a "difference" region 
consisting of all parts of this region that are not parts of the source region. Both forms 
return a reference to the resulting region. 


Seealso TSize class, TRegion::operator += 


operator &= 

TRegion& operator &=(const TRegion& source); 

TRegion& operator &=(const TRect& source); 

Creates the intersection of this region with the given source region or rectangle, and 
returns a reference to the result. 


Seealso TRect class 


operator |= 
_ TRegion& operator |=(const TRegion& source); 
TRegion& operator |=(const TRect& source); 


386 ObjectWindows Reference Guide 


TRelationship enum 


Creates the union of this region and the given source region or rectangle, and returns a 
reference to the result. 


See also TRect 


operator *= 

TRegion& operator “=(const TRegion& source); 

TRegion& operator “=(const TRect& source); 

Creates the union of this region and the given source region or rectangle, but excludes 
any overlapping areas. Returns a reference to the resulting region object. 


See also TRect class 


operator HRGN() 
operator HRGN() const; 
Typecast operator. HRGN is the data type representing the handle to a physical region. 


SetRectRgn 
void SetRectRgn(const TRect& a 
Creates a rectangle of the size given by rect. 


Seealso TRect class 


Touches 
bool Touches(const TRect& rect) const; 
Returns true if this region touches the given rectangle. 


Seealso TRect class 


enum TRelationship {ImAsls, ImPercentOf, ImAbove, ImLeftOf = ImAbove, ImBelow, ImRightOf = ImBelow, 
ImSameAs, ImAbsolute}; 


Used by the TLayoutConstraint struct, TRelationship specifies the relationship between 
the edges and sizes of one window and the edges and sizes of another window (which 
can be a parent or sibling). These relationships can be specified as either the same value 
as the sibling or parent window (ImAslIs), an absolute value (ImAbsolute), a percent of 
one of the windows (JmPercentOf), a value that is either added above (ImAbove) or left 
(ImLeftOf) of one of the windows, or a value that is subtracted from below (JmBelow) or 
right (ImRightOf) of one of the windows. 


See also TLayoutConstraint struct 


TReplaceDialog creates a modeless dialog box that lets the user enter a selection of text to 
replace. Because these are model dialog boxes, you can search for text, edit the text in the 
window, and return to the dialog box to enter another selection. TReplaceDialog uses the 


Chapter 2, ObjectWindows library reference 387 


| TResponseTableEntry class 


TFindReplaceDialog::TData class to set the user-defined values for the disigs box, such as 
the text strings to search for and replace. 


Public constructor 


Constructor 
—TReplaceDialog(TWindow* parent, TData& data, TResID ‘SieNane: 0, const char far* title=0, 
_ TModule* module=0); | 
Constructs a TReplaceDialog object with a parent window, resource ID, template name, 
caption, and module instance. The data parameter is a reference to the 
TFindReplaceDialog::TData class that contains information about the appearance and 
functionality of the dialog box, such as the user-entered text strings to search for and 
replace. 


Seealso TFindReplaceDialog::TData class 


Protected member function 


DoCreate 
HWND DoCreate(); 
Creates a modeless find and replace dialog box. 


Seealso 9 TDialog::DoCreate 


TResponsefableEntry class | eventhan.h 


A template class, TResponseTableEntry lets you define a pattern for entries into a 
response table. Entries consist of a message, a notification code, a resource ID, a 
dispatcher type, and a pointer to a member function. 


See DECLARE_RESPONSE_TABLE and DEFINE_RESPONSE_TABLE for additional 
information about the macros in the response tables. 


Public data members 


Dispatcher 
TAnyDispatcher Dispatcher; . 
An abstract dispatcher type that points to one of the dispatcher functions. 


Id 

uint Id; 

Contains the menu or accelerator resource ID (CM_xxxx) for the message response 
member function. 


Msg 
uint Msg; 
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Contains the ID of the message sent. These can be command messages, child id 
messages, notify-based messages such as LBN_SELCHANGE, or messages such as 
LBUTTONDOWN. 


NotifyCode 

uint NotifyCode; 

Stores the control notification code (for example, ID_LISTBOX) for the response table 
entry. These can be button, combo box, edit control, or list box notification codes. 


Pmf 
PMF Pmnif; 
Points to the actual handler or member function. 


Type definitions 


T 

typedef void(T_*PMF)(); 

Type for a generic member function that responds to notification messages. T is the 
template for the response table. | 


Lin: nitions 


Form 1 


Form 2 


TRgbQuad is a support class derived from the structure tagRGBQUAD, which is defined 
as follows: 


typedef struct tagRGBQUAD { 
uint8 rgbBlue; 
uint8 xrgbGreen; 
uint8 rgbRed; 
uint8 rgbReserved; 
} RGBQUAD; 


where rgbBlue, rgbGreen, and rgbRed specify the relative blue, green, and red intensities 
of a color. rgbReserved is not used and must be set to 0. 


TRgbQuad is used in conjunction with the classes TPalette and TColor to simplify 
RGBQUAD-based color operations. Constructors are provided to create TRgbQuad 
objects from explicit RGB values, from TColor objects, or from other TRgbQuad objects. 


Public constructors 


Constructors 

TRgbQuad(int r, int g, int b); 

Creates a TRgbQuad object with rebRed, rgbGreen, and rgbBlue set to r, g, and b 
respectively. rgbReserved is set to 0. 


TRgbQuad(TColor c); 
Creates a TRgbQuad object with rgbRed, rgbGreen, rgbBlue set to c.Red, c.Green, c.Blue 
respectively. rgbReserved is set to 0. 


Chapter 2, ObjectWindows library reference 389 


TRgbTriple class 


Form 3 


TRgbQuad(const RGBQUAD far& q); 
Creates a TRebQuad object with the same values as the referenced RGBQUAD object 


Seealso TColor: ‘Red, TColor::Green, TColor::Blue 


Form 1 


Form 2 


Form 3: 


TRgbTriple is a support class derived from the structure MSRSIEOUE: which is defined as 
follows: 


typedef struct tagRGBTRIPLE { 
uint8 rgbBlue; 
uint8 rgbGreen; 
uint8 rgbRed; 

} RGBTRIPLE; 


| rgbBlue, rgbGreen, and rgbRed specify the cave blue, green, and red intensities for a 


color. 


TRebTriple is used in conjunction with the classes TPalette and TColor to seal bmci- 
color-based operations. Constructors are provided to create T’RgbTriple objects from 
explicit RGB values, from TColor objects, or from other TRgbTriple objects. 


Public constructors 


Constructors 

TRgbTriple(int r, int g, int b); 

Creates a TRgbTriple object with rgbRed, rgbGreen, and rab Blue set to r, g, and D 
respectively. 


_ TRgbTriple(TColor c); 


Creates a T’RgbTriple object with heiRal rgbGreen, rgbBlue set toc. Red, c.Green, and c.Blue 
respectivelyrgbReserved is set to 0. 


TRgbTriple(const RGBTRIPLE faré& t); 
Creates a TRgbTriple object with the same values as the referenced RGBTRIPLE object. 


Seealso tag RGBTRIPLE struct, TColor::Red, TColor::Green, TColor::Blue 


_TScreenDC class a de.h 


Derived from TWindowDC, TScreenDC is a DC class that provides direct access to the 
screen bitmap. T'ScreenDC gets a DC for handle 0, which is for the whole screen with no 
clipping. Handle 0 paints on top of other windows. 


Public constructor 


Constructor | 
TScreenDC(); 
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Default constructor for TScreenDC objects. 


TScrollBar class scrollba.h 


Form 1 


Form 2 


TScrollBar objects represent standalone vertical and horizontal scroll bar controls. Most 
of TScrollBar's member functions manage the scroll bar's sliding box (thumb) position 
and range. 


One special feature of the type TScrollBar is the notify-based set of member functions 
that automatically adjust the scroll bar's thumb position in response to scroll bar 
messages. 


Never place TScrollBar objects in windows that have either the WS_HSCROLL or 
WS_VSCROLL styles in their attributes. 


TScrollBar is a streamable class. 


Public data members 


LineMagnitude 

int LineMagnitude; 

LineMagnitude is the number of range units to scroll the scroll bar when the user requests 
a small movement by clicking on the scroll bar's arrows. TScrollBar's constructor sets 
LineMagnitude to 1 by default. (The scroll range is 0-100 by default.) 


Seealso TScroll/Bar::SetupWindow 


PageMagnitude 

int PageMagnitude; 

PageMagnitude is the number of range units to scroll the scroll bar when the user 
requests a large movement by clicking in the scroll bar's scrolling area. TScrollBar's 
constructor sets PageMagnitude to 10 by default. (The scroll range is 0-100 by default.) 


Public constructors 


Constructors 

TScrollBar(TWindow* parent, int id, int x, int y, int w, int h, bool isHScrollBar, TModule* module = 0); 
Constructs and initializes a TScrollBar object with the given parent window (parent), a 
control ID (id), a position (x, y), and a size of (w, h). Invokes the TControl constructor with 
similar parameters. If isHScrollBar is true, adds SBS_HORZ to the window style. If not 
true, adds SBS_VERT. If the supplied height for a horizontal scroll bar or the supplied 
width for a vertical scroll bar is 0, a standard value is used. LineMagnitude is initialized to 
1 and PageMagnitude is set to 10. 


TScrollBar(TWindow* parent,int resourceld, TModule* module = 0); 
Constructs a TScrollBar object to be associated with a scroll bar control of a TDialog. 
Invokes the TControl constructor with identical parameters. 


The resourceld parameter must correspond to a scroll bar resource that you define. 
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See also TControl::TControl 
Public member functions 


DeltaPos , 
virtual int DeltaPos(int delta); 

Calls SetPosition to change the scroll bar's thumb position by the value supplied in delta. 
A positive delta moves the thumb down or right. A negative delta value moves the 
thumb up or left. The new thumb position is returned. 


See also TScrollBar::SetPosition 


EvHScroll 

void EvHScroll(uint scroliCode, uint thumbPos, HWND hWndCtl); 

Response table handler that calls the virtual function (SBBottom, SBLineDown and so on) 
in response to messages sent by TWindow::DispatchScroll. 


| EwVScroll 
void EvVScroll(uint scrollCode, uint thumbPos, HWND hWndCtl); 
Response table handler that calls the virtual function (SBBottom, SBLineDown and so on) 
in response to messages sent by TWindow::DispatchScroll. 
GetPosition 
virtual int GetPosition() const; | 
Returns the scroll bar's current thumb Suseen: 


Seealso TScrollBar::SetPosition, TScrollBarData struct 


-GetRange 
virtual void GetRange(int& min, int& max) const: 
Returns the end values of the present range of scroll bar thumb positions in min and 
max. 


See also TScrollBar::SetPosition, TScrollBar::SetRange, TScrollBarData struct. 


SBBottom 
virtual void SBBottom(); _ 
Calls SetPosition to move the thumb to the bottom or right of the scroll bar. SB_BOTTOM 


is called to respond to the thumb being dragged to the bottom or rightmost position of 
the scroll bar. 


See also TScrollBar::SetPosition 


SBLineDown 

virtual void SBLineDown(); 

Calls SetPosition to move the thumb down or right (by LineMagnitude units). 
SBLineDown is called to respond to a click on the bottom or right arrow of the scroll bar. 


See also TScrollBar::SetPosition 


SBLineUp 
virtual void SBLineUp(); 
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Calls SetPosition to move the thumb up or left (by LineMagnitude units). SBLineUp is 
called to respond to a click on the top or left arrow of the scroll bar. 


~Seealso TScrollBar::SetPosition 


SBPageDown 

virtual void SBPageDown(); | 

Calls SetPosition to move the thumb down or right (by PageMagnitude units). 
SBPageDown is called to respond to a click in the bottom or right scrolling area of the 
scroll bar. 


Seealso TScrollBar::SetPosition 


SBPageUp 

virtual void SBPageUp(); 

Calls SetPosition to move the thumb up or left (by PageMagnitude units). SBPageUp is 
called to respond to a click in the top or left scrolling area «:f the scroll bar. 


Seealso TScrollBar::SetPosition 


SBThumbPosition 

virtual void SBThumbPosition(int thumbPos); 

Calls SetPosition to move the thumb. SBThumbPosition is called to respond when the 
thumb is set to a new position. 


Seealso TScrollBar::SetPosition 
SBThumbTrack 


virtual void SBThumbTrack(int thumbPos); 
Calls SetPosition to move the thumb as it is being dragged to a new position. 


See also TScrollBar::SetPosition 
SBTop 
virtual void SBTop(); 


Calls SetPosition to move the thumb to the top or right of the scroll bar. SBTop is called to 
respond to the thumb being dragged to the top or rightmost position on the scroll bar. 


Seealso TScrollBar::SetPosition 
SetPosition 
virtual void SetPosition(int thumbPos); 


Moves the thumb to the position specified in ThumbPos. If ThumbPos is outside the 
present range of the scroll bar, the thumb is moved to the closest position within range. 


Seealso TScrollBar::GetPosition 


SetRange 
virtual void SetRange(int min, int max); 
Sets the scroll bar to the range between min and max. 


Seealso TScrollBar::GetRange 


Transfer 
uint Transfer(void* buffer, TTransferDirection direction); 
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Transfers scroll bar data to or fom the transfer buffer pointed to by buffer. buffer is 
expected to point to a TScrollBarData structure. | 


Data is transferred to or from the transfer buffer if tdGetData or tdSetData is supplied as 
the direction. 


Transfer always returns the size of the transfer data (the size of the TScrollBarData 
structure). To retrieve the size of this data without transferring data, pass tdSizeData as 
the direction. | 


Seealso TScrollBarData struct 


Protected member functions 


GetClassName 
char far* GetClassName(); 
Returns the name of TScrollBar's registration class, "SCROLLBAR 


SetupWindow 
void SetupWindow(); 
Sets the scroll bar's range to 0, 100. To redefine this range, call SetRange. 


Seealso TScrollBar::SetRange 


Response table entries 


EV_WM_HSCROLL EvHScroll 
EV_WM_VSCROLL —__EVScroll 


The TScrollBarData structure contains integer values that represent a range of thumb 
positions on the scroll bar. TScrollBar's function GetRange calls TScrollBarData to obtain 
the highest and lowest thumb positions on the scroll bar. GetPosition calls TScrollBarData 
to obtain the current thumb position on the scroll bar. 


See also 
TScrollBar::Transfer 


Public data members 


HighValue 
int HighValue; 
Contains the highest value of the thumb position in the scroll bar's range. 


Seealso TScrollBar::GetRange 
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LowValue 
int LowValue; 
Contains the lowest value of thumb position in the scroll bar's range. 


Seealso TScrollBar::GetRange 


Position 
int Position; 
Contains the scroll bar's thumb position. 


Seealso TScrollBar::GetPosition 


TScroller class | scroller.h 


TScroller supports an automatic window-scrolling mechanism (referred to as 
autoscrolling) that works in conjunction with horizontal or vertical window scroll bars 
(it also works if there are no scroll bars). When autoscrolling is activated, the window 
automatically scrolls when the mouse is dragged from inside the client area of the 
window to outside that area. If the AutoMode data member is true, TScroller performs 
autoscrolling. 


To use TScroller, set the Scroller member of your TWindow descendant to a TScroller 
object instantiated in the constructor of your TWindow descendant. TScroller is a 
streamable class. 


Public data members 


AutoMode 
bool AutoMode; 
Is true if automatic scrolling is activated. 


AutoOrg 
bool AutoOrg; 
Is true if scroller offsets original. 


HasHScrollBar, HasVScrollBar 
bool HasHScrollBar, HasVScrollBar; 
Is true if scroller has horizontal or vertical scroll. 


TrackMode 
bool TrackMode; 
Is true if track scrolling is activated. 


Window 
TWindow* Window; 7 
Points to the window whose client area scroller is to be managed. 


XLine, YLine 
int XLine, YLine; 


Chapter 2, ObjectWindows library reference 395 


TScroller class | 


Specifies the number of logical device units per line to scroll the rectangle i in the 
horizontal (X) and vertical (Y) directions. 


XPage, YPage 

int XPage, YPage; 

Specifies the number of logical device units per page to scroll the rectangle in the 
horizontal (X) and vertical (Y) directions. 


XPos, YPos 

long XPos, YPos; 

Specifies the current position of the rectangle in horizontal (XPos) and vertical (YPos) 
scroll units. 


XRange, YRange 
long XRange, YRange; 
Specifies the number of horizontal and vertical scroll units. 


XUnit, YUnit 

int XUnit, YUnit; | 

Specifies the amount (in logical device units) to scroll the rectangle i in the horizontal (X) 
and vertical (Y) directions. The rectangle is scrolled right if XUnit is positive and left if 

XUnit is negative. The rectangle is scrolled down if YUnit is positive and up if YUnit is 
negative. 


Public constructor and destructor 


Constructor 

TScroller(TWindow* window, int Unit int yUnit, long xRange, long yRange); 

Constructs a TScroller object with window as the owner window, and xUnit, ylnit, 
xRange, and yRange as xUnit, yUnit, xRange and yRange, respectively. Initializes data 
members to default values. HasHScrollBar and HasVScrollBar are set according to the 
scroll bar attributes of the owner window. 


Destructor 
virtual ~TScroller(); 
Destructs a TScroller object. Sets owning window's Scroller number variable to 0. 


Public member functions 


AutoScroll 

virtual void AutoScroll(); 

Scrolls the owner window's display in response to the mouse being dragged from inside 
to outside the window. The direction and pi amount by which the sa is scrolled 
depend on the current position of the mouse. 


BeginView 

virtual void BeginView(TDC& dc, TRect& rect); 

If TScroller_AutoOrg is true (default condition), Begin View sienaeely offsets the 
origin of the logical coordinates of the client area by XPos, YPos during a paint — 
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operation. If AutoOrg is false (for example, when the scroller is larger than 32,767 units), 
you must set the offset manually. 


EndView 

virtual void EndView(); 

Updates the position of the owner window's scroll bars to be coordinated with the 
position of the TScroller. 


HScroll 

virtual void HScroll(uint scrollEvent, int thumbPos); 

Responds to the specified horizontal scrollEvent by calling ScrollBy or ScrollTo. The type 
of scroll event is identified by the corresponding SB_ constants. thumbPos contains the 
current thumb position when the scroller is notified of SB_THUMBTRACK and 
SB_THUMBPOSITION scroll events. 


IlsAutoMode 
virtual bool IsAutoMode(); 
IsAutoMode is true if automatic scrolling is activated. 


Seealso TScroller::AutoMode 


IsVisibleRect 
bool IsVisibleRect(long x, long y, int xExt, int yExt); 
Is true if the rectangle (x, y, xExt, and yExt) is visible. 


SetPageSize 

virtual void SetPageSize(); 

Sets the XPage and YPage data members to the width and height (in XUnits and. YUnits) 
of the owner window's client area. 


Seealso TScroller::XPage, YPage, TScroller::XUnit, YUnit 


SetRange 

virtual void SetRange(long xRange, long yRange); 

Sets the xRange and yRange of the TScroller to the parameters specified. Then calls 
SetSBarRange to synchronize the range of the owner window's scroll bars. 


Seealso TScroller::SetSBarRange 
SetSBarRange 


virtual void SetSBarRange(); 
Sets the range of the owner window's scroll bars to match the range of the T’Scroller. 


SetUnits 

virtual void SetUnits(int xUnit, int yUnit); 

Sets the XUnit and YUnit data members to TheXUnit and TheY Unit, respectively. 
Updates XPage and YPage by calling SetPageSize. 


Seealso TScroller::XPage, YPage, TScroller::XUnit, YUnit 


ScrollBy 
void ScrollBy(long dx, long dy); 


Chapter 2, ObjectWindows library reference 397 


TSeparatorGadget class 


Scrolls to a position calculated using the passed delta values (dx and dy). A positive delta 
position moves the thumb position down or fee A negative delta position moves the 
thumb up or left. | 


ScrollTo 
virtual void ScrollTo(long x, long y); 
Scrolls the rectangle to the position specified in x and y. 


SetWindow 
void SetWindow(TWindow* win); 
Sets the owning window to win. 


VScroll 
virtual void VScroll(uint scrollEvent, int thumbPos); 


Responds to the specified vertical scrollEvent by calling ScrollBy or ScrollTo. The type of 
scroll event is identified by the corresponding SB_ constants. thumbPos contains the 
current thumb position when the scroller is notified of SB_THUMBTRACK and 
SB_THUMBPOSITION scroll events. 


Seealso TScroller::ScrollTo 
XScrollValue | 
int XScrollValue(long rangeUnit); 


XScrollValue converts a horizontal range value from the scroll bar to a horizontal scroll — 
value. 


See also TScroller::YScrollValue 


XRangeValue 

int XRangeValue(int scrollUnit); 

XRangeValue converts a horizontal scroll value from the scroll bar to a horizontal range 
value. | | 


Seealso TScroller::YRangeValue 


YScrollValue 
int YScrollValue(long rangeUnit); 
YScrollValue converts a vertical range value from the scroll bar to a vertical scroll value. 


Seealso TScroller::XScrollValue 


YRangeValue 
int YRangeValue(int scrollUnit); | | 
YRangeValue converts a vertical scroll value from the scroll bar to a vertical range value. 


See also TScroller::XRangeValue 


_TSeparatorGadget class SS gadget-h 


TSeparatorGadget is a a simple class you can use to create a separator between gadgets. To 
do so, you must specify the size of the separator in units of SM_CXBORDER (width of 


398 ObjectWindows Reference Guide 


TSlider class 


the window frame) and SM_CYBORDER (height of the window frame). The right and 
bottom boundaries of the separator are set after calling GetsystemMetrics. By default, the 
separator disables itself and turns off shrink-wrapping. Note that the default border 
style is none. 


see also 
TGadget::TBorderStyle enum 


Public member function 


TSeparatorGadget 

TSeparatorGadget(int size = 6); 

Used for both the width and the height of the separator, size is initialized at 6 border 
units (the width or height of a thin window border). 


TSlider class | sliderh 


An abstract base class derived from TScrollBar, TSlider defines the basic behavior of 
sliders (controls that are used for providing nonscrolling, position information). Like 
scroll bars, sliders have minimum and maximum positions as well as line and page 
magnitude. Sliders can be moved using either the mouse or the keyboard. If you use a 
mouse to move the slider, you can drag the thumb position, click on the slot on either 
side of the thumb position to move the thumb by a specified amount (PageMagnitude), or 
click on the ruler to position the thumb at a specific spot on the slider. The keyboard’s 
Home and End keys move the thumb position to the minimum (Min) and maximum 
(Max) positions on the slider. 


You can use TSlider’s member functions to cause the thumb positions to automatically 
align with the nearest tick positions. (This is referred to as snapping.) You can also 
specify the tick gaps (the space between the lines that separate the major divisions of the 
X- or Y-axis). 


The sample program SLIDER.CPP on your distribution disk displays the aimee 
thermostat that uses sliders. 


Home Heater-Simuls 


Maximum position 


Thumb position 


Vertical slider 


Minimum position 


Horizontal slider 


See the two derived classes, THSlider and TVSlider, for specific details about horizontal 
and vertical sliders. 
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Public constructor and destructor 


Constructor 

TSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResld thumbResld, TModule* noadee 0); 
Constructs a slider object setting Pos and ThumbRgn to 0, TicGap to Range divided by 10, 
SlotThick to 17, Snap to true, and Sliding to false. Sets Attr.W and Attr.H to the values in X_ 
and Y. ThumbReslId is set to thumbResld. 


Destructor 
~TSlider(); | 
Destructs a TSlider object and deletes ThumbRgn. 


Public member functions 


GetPosition | 
int GetPosition() const; 
- Returns the slider’s current thumb position. Overloads TScrollBar’s virtual function. 


Seealso TSlider::SetPosition 


GetRange 

void GetRange(int &min, int &max) const; 

Returns the end values of the present range of slider thumb positions in min and max. 
Overloads TScrollBar’s virtual function. 


Seealso ‘Slider::SetRange 


SetPosition 

void SetPosition(int thumbPos); | 
Moves the thumb to the position specified in thumbPos. If thumbPos is outside the — 
present range of the slider, the thumb is moved to the closest position within the 
specified range. Overloads TScrollBar’s virtual function. 


Seealso TSlider::GetPosition 


SetRange 
void SetRange(int min, int max); 
Sets the slider to the range between min and max. Overloads TScrollBar's virtual 


function. 
Seealso TSlider::GetRange 


SetRuler 

void SetRuler(int ticGap, bool snap = false); 

Sets the slider’s ruler. Each slider has a built-in ruler that is drawn with the slider. The 
ruler, which can be blank or have tick marks on it, can be created so that it forces the 
thumb to snap to the tick positions automatically. 
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Protected member functions 


EvEraseBkgnd 

bool EvEraseBkgnd(HDC hDC); 

Responds to a WM_ERASEBKGND message and erases the background of the slider 
when the slider is changed. Calls the virtual functions PaintRuler, PaintSlot, and 
PaintThumb to paint the components of the slider. To avoid flickering, EvEraseBkgnd is 
called to erase the background as the painting occurs. 


Seealso TSlider::EvPaint 


EvGetDigCode 

uint EvGetDigCode(MSG far* msg); 

Responds toa WM_GETDLGCODE message and let the dialog manater control the 
response to a DIRECTION key or TAB key input. Captures cursor-movement keys to 
move the thumb by returning a DLGC_WANTARROWS message, which indicates that 
direction keys are desired. The msg parameter indicates the kind of message, for example 
a acontrol or a command message, sent to the dialog box manager. 


EvGetDlgCode returns a code that indicates how the control message is to be treated. 


Seealso TButton::EvGetDlgCode, TWindow::DefaultProcessing, DLGC_xxxx dialog 
control message constants 


EvKeyDown 

void EvkeyDown(uint key, uint repeatCount, uint flags); 

EvKeyDown translates the virtual key code into a movement and then moves the thumb. 
key indicates the virtual key code of the pressed key, repeatCount holds the number of 
times the same key is pressed, and flags contains one of the following messages, which 
translate to virtual key (VK) codes: 


SB_PAGEDOWN VK_NEXT 


SB_BOTTOM VK_END 

SB_TOP VK_HOME 

SB_LINEUP VK_LEFT(same as SB_LINELEFT) 
SB_LINEUP VK_UP 

SB_LINEDOWN VK_RIGHT(same as SB_LINERIGHT) 
SB_LINEDOWN VK_DOWN 
EvKillFocus 


void EvKillFocus(HWND hWndGetFocus); 
In response to a WM_KILLFOCUS message sent to a window that is losing the 
keyboard, EvKillFocus hides and then destroys the caret. 


EvLButtonDbIiCik 
void EvLButtonDbiClk(uint modKeys, TPoint& point); 
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Responds to a WM_ LBUTTONDBLCLK message (which indicates the user double- 
clicked the left mouse button), then throws away the messages so the base class doesn’t 
receive them. 


EvLButtonDown 
void EvLButtonDown(uint modKeys, TPoint& point); 
Responds to a mouse press by positioning the thumb or beginning a mouse drag. If the 
mouse is pressed down while it is over the thumb, EvLButtonDown enters sliding state. 
If the mouse is in the slot, EvLButtonDown pages up or down. If the mouse is on the 

_ ruler, EvLButtonDown jumps to that position. EvLButtonDown generates a scroll code of 
SB_THUMBPOSITION, SB_LINEUP, SB_LINEDOWN, SB_PAGEUP, 
SB_PAGEDOWN, SB_THUMBTRACK. 


Seealso TSlider::EvLButtonUp 


EvLButtonUp 

void EvLButtonUp(uint modKeys, TPoint& point); 

If the mouse button is released, EvLButtonUp ends nes paging, or jumping to a 
position on the ruler. 


See also TSlider::EvLButtonDown 


EvMouseMove | 

void EvMouseMove(uint modKeys, TPoint& point); 

Moves the mouse to the indicated. position. If the mouse is being dragged, EvuMouseMove 
positions the thumb and sends the appropriate message to the parent window. 


EvPaint 

void EvPaint(); 

Paints the entire slider—truler, slot, and thumb. Calls the virtual functions PaintRuler, 
PaintSlot, and PaintThumb to paint the components of the slider. 


Seealso TSlider::EvEraseBkgnd 


EvSetFocus 
void EvSetFocus(HWND hWndLostFocus); 
Creates a blinking caret to show the focus i in the current window. 


EvSize 
void EvSize(uint size Type, TSize& size); : 
Recalculates the size of the slider when the window size is changed. 


GetBkColor 

void GetBkColor(TDC& de); 

Sends a WM_CTLCOLOR message to the parent and calls de: ‘GetBkColor to extract the 
background color for the slider. , 


HitTest 

virtual int HitTest(TPoint& point) = 0; 

Gets information about where a given X, Y location falls on the slider. The return value 
is in scrollCodes. Each of the derived classes performs comparisons to return a scroll 
code. 
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Seealso TSlider::NotifyParent 


NotifyParent 
virtual void NotifyParent(int scrollCode, int pos=0) = 0; 
Sends a WS_HSCROLL or WS_VSCROLL message to the parent window. 


Seealso TVSlider::HitTest 


PaintRuler 
virtual void PaintRuler(TDC& dc) = 
Paints the ruler. It is assumed that the slot or thumb do not overlap the ruler. 


PaintSlot 
virtual void PaintSlot(TDC& dc) = 0; 
Paints the slot in which the thumb slides. 


PaintThumb 

virtual void PaintThumb(TDC& dec); 

Paints the thumb itself using a resource DIB translated to the current system button 
colors and which overlaps the slot. 


PointToPos 
virtual int PointfoPos(TPoint& point) = 0; 
Translates an X,Y point to a position in slider units. 


Seealso TSlider::PosToPoint 


PosToPoint 
virtual TPoint PosToPoint(int pos) = 
Translates a position in slider units to an X,Y point. 


Seealso TSlider::PointToPos 


SetupThumbRgn 

virtual void SetupThumbRgn(); 

Creates the region that defines the thumb shape for this slider class. Although the 
default region is a simple bounding rectangle, it can be any shape. While the slider 
thumb is being moved, this region is used for testing the mouse position and updating 
the thumb position. 


Seealso TSlider::ThumbRgn 
SetupWindow 


void SetupWindow(); 
Calls TScrollBar::SetupWindow and Sehibs Tien ReH tS to set up the window. 


Seealso TScrollBar::SetupWindow 


SlideThumb 
virtual void SlideThumb(TDC& de, int thumbPos); 
Slides the thumb to a given position and performs the necessary blitting and painting. 


SnapPos 
int SnapPos(int pos); 
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 Constrains pos so it is in the range from Min to Max and (if snapping is enabled) 
performs snapping by rounding pos to the nearest TicGap. 


Seealso TSlider::TicGap 


Protected data members 


BkColor 
TColor BkColor; 
Stores the background color of the slider. 


CaretRect 
TRect CaretRect; | 
Refers to the position of the caret’s rectangle. 


Max 

int Max; 

Contains the maximum value of the slider position. 
Min 

int Min; 

Contains the minimum value of the slider position. 


MouseOffset 

static TSize MouseOffset; 

MouseOffset shows the offset from the rectangle's original top left position to the position 
where the mouse is clicked. Thus, when the rectangle is moved, it can maintain the same 
relationship to the position of the mouse click. 


Pos 
int Pos; 
Indicates where the thumb is positioned on the slider. 


Seealso TSlider::GetPosition 


Range 
uint Range; | 
Contains the difference between the maximum and minimum range of the slider. 


SlideDC 

static TDC* SlideDC; 

SlideDC is used while the mouse is down and the thumb is sliding. It reflects the 
movement of the mouse on the DC. 


Sliding 
bool Sliding; | 
Sliding is true if the thumb is sliding. Otherwise, false. 


SlotThick 
— int SlotThick; 
Indicates the thickness of the slot. Set to 17 by default. 
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Snap is true if snapping is activated; otherwise false. 


ThumbRect 
TRect ThumbRect; 


Holds the thumb’s bounding rectangle. 


ThumbResld 
TResid ThumbResid; 


ThumbResld is the bitmap resource ID for the thumb knob. 


ThumbRgn 
virtual void Setup ThumbRgn(); 


Creates the region that defines the thumb shape for this slider class. Although the 
default region is a simple bounding rectangle, it can be any shape. While the slider 
thumb is being moved, this region is used for testing the mouse position and updating 


the thumb position. 


Seealso TSlider::ThumbRen 


TicGap 
int TicGap; 


Specifies the amount of space in pixels between ticks. 


Response table entries 


EV_WM_ERASEBKGND 
EV_WM_GETDLGCODE 
EV_WM_KEYDOWN 
EV_WM_KILLFOCUS 
EV_WM_LBUTTONDBLCLK 
EV_WM_LBUTTONDOWN 
EV_WM_LBUTTONUP 
EV_WM_MOUSEMOVE 
EV_WM_PAINT 
EV_WM_SETFOCUS 
EV_WM_SIZE 


THSlider class 


EvEraseBkgnd 
EvGetDlgCode 
EvKeyDown 
EvKillFocus 
EvLButtonDbIClk 
EvLButtonDown 
EvLButtonUp 
EvMouseMove 
EvPaint 
EvSetFocus 
EvSize 


slider.h 


Derived from TSlider, THSlider provides implementation details for horizontal sliders. 
See TSlider for an illustration of a horizontal slider. 
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Public constructors 


Constructors 
THSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResld thumbResld = IDB _HSLIDERTHUMB, 
TModule* module = 0); 


~ Constructs a slider object with a default bitmap resource ID of IDB_HSLIDERTHUMB 
for the thumb knob. 


‘Protected memberfunetons 


HitTest 

int HitTest(TPoint& point); 

Overrides TSlider's virtual function and gets information about where a given X, Y 
location falls on the slider. The return value is in scrollCodes. 


Seealso TSlider::HitTest 


NotifyParent 

void NotifyParent(int scrollCode, int pos=0); 

Overrides TSlider's virtual function and sends a WS_HSCROLL message to the parent 
window. | 


Seealso TSlider::NotifyParent 


PaintRuler 
void PaintRuler(TDC&); 
Overrides TSlider's virtual function and paints the horizontal ruler. 


See also TSlider::PaintRuler 
PaintSlot 


void PaintSlot(TDC&); 
Overrides TSlider's virtual function and paints the slot in which the thumb slides. 


See also TSlider::PaintSlot 
PointToPos 
int PointToPos(TPoint& point); 


Overrides TSlider's virtual function and translates an X,Y point to a position in slider 
units. 


Seealso TSlider::PointToPos 


PosToPoint 

~ TPoint PosToPoint(int pos); 
Overrides TSlider's virtual function and translates a position in slider units to an X,Y 
point. 


~Seealso TSlider::PosToPoint 
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Derived from TSlider, TVSlider provides implementation details for vertical sliders. See 
TSlider for an illustration of a vertical slider. 


Public constructor 


Constructor 

TVSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResid thumbResld = IDB VSLIDERTHUMB, 
TModule* module = 0); 

Constructs a vertical slider object with a default bitmap resource ID of 

IDB_VSLIDERTHUMB for the thumb knob. 


Protected member functions 


HitTest 

int HitTest(TPoint& point); 

Overrides TSlider's virtual function and gets information about where a given X, Y 
location falls on the slider. The return value is in scrollCodes. 


Seealso TSlider::HitTest 


NotifyParent 

void NotifyParent(int scrollCode, int pos=0); 

Overrides T’Slider’s virtual function and sends a WS_VSCROLL message to the parent 
window. 


Seealso TSlider::NotifyParent 
PaintRuler 


void PaintRuler(TDC& dc); 
Overrides TSlider's virtual function and paints the vertical ruler. 


Seealso TSlider::PaintRuler. 
PaintSlot 


void PaintSlot(TDC& dc); 
Overrides TSlider's virtual function and paints the slot in which the thumb slides. 


Seealso TSlider::PaintSlot 
PointToPos 
int PointfoPos(TPoint& point); 


Overrides TSlider's virtual function and translates an X,Y point to a position in slider 
units. 


Seealso TSlider::PointToPos 


PosToPoint 
TPoint PosToPoint(int pos); 
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Overrides TSlider's virtual function and franclates a position in slider units to an X,Y 
— point. 


Seealso TSlider::PosToPoint 


TSortedStringArray class - validate.h 


Implements a list of ASCII characters stored as a sorted array of elements that are string 
objects. TSortedStringArray can perform many of the string manipulation functions, such 
as adding and removing elements from the array, and provides many of the common 
C++ functions implemented by container classes. 


See also 
TValidator class, TLookupValidator class | 


Public constructor 


Constructor 

TSortedStringArray(int upper, int lower, int delta); 

Constructs a TSortedStringArray object with an upper boundary of upper, a lower 
boundary of lower, and a growth delta of delta. 


Type definitions 


void 
typedef void (*IterFunc)(string&, void*); | 
Function type used as a parameter to the ForEach member function. 
int 
typedef int (*CondFunc)(const string&, void*); 
_ Function type used as a parameter to the FirstThat and LastThat member functions. 


Public member functions 


Add 

int Add(const string& t); 

Adds an element to the array at the next available index position. Adding an. element 
beyond the upper boundary leads to an overflow condition. If this condition occurs and 
the growth delta, delta, (from the constructor) is nonzero, the array is expanded (by 
sufficient multiples of delta bytes) to accommodate the addition. If delta is zero, Add fails. 
Add returns 0 if the object could not be added. 


ArraySize 
unsigned ArraySize() const; 
Returns the size of the array. 
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Destroy 
int Destroy(const string& t); 
Removes the element specified by ¢ and deletes it. 


int Destroy(int loc); 
Removes an element from the array at the specified index location, loc, and deletes it. 


Detach 

int Detach(const string& t); 

Removes the specified element from the array. Returns 1 if successful; otherwise, 
returns 0. 


int Detach(int loc); 
Removes an element from the array at the specified index location, loc. Returns 1 if 
successful; otherwise, returns 0. 


Find 

int Find(const string& t) const; 

Finds the first element represented by t and returns the index where the element is 
located. 


FirstThat 

string* FirstThat(CondFunc cond, void* args) const; 

Returns a pointer to the first element in the array that satisfies a specified condition. cond 
is the test function pointer that returns true for a specified condition. args contains the 
various arguments passed. Returns 0 if no element in the array satisfies the given 
condition. Because FirstThat creates its own internal iterator, you can use it as a search 
function also. : 


Flush 
void Flush(); 
Removes all elements from the array without destroying the array itself. 


ForEach 

void ForEach(IterFunc iter, void* args); 

Creates an internal iterator to execute the specified function, iter, for each element in the 
array. Use the args argument to pass various kinds of data to this function. 


GetitemsinContainer 
unsigned GetltemsinContainer() const; 
Returns the number of elements in the array. 


HasMember 
int HasMember(const string& t) const; 
Returns 1 if the element specified by t exists in the array; otherwise returns 0. 


IsEmpty 
int lsEmpty() const; 
Returns 1 if the array is empty; otherwise, returns 0. 


—IsFull 


int IsFull() const 
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Form 1 


Form 2 


Returns 1 if the array is full; otherwise, returns 0. 


LastThat 

string* LastThat(CondFunc cond, void* args) const; 

Returns a pointer to the last element in the array that satisfies a specified condition. cond 
is the test function pointer that returns true for a specified condition. args contains the 
various arguments passed. Returns 0 if no element in the array satisfies the given 
condition. Because LastThat creates its own internal iterator, you can use it as a search 
function also. 


LowerBound _ 
int LowerBound() const; 
Returns the array's lower boundary. 


operator [] 

string& operator [](int loc); 

Returns a reference to the element at the location specified by loc. This version resizes 
the array if it is necessary to make loc a valid index. 


string& operator [](int loc) const; ! 
Returns a reference to the element at the location specified by loc. This version throws an 
exception in the debugging version on an attempt to index out of bounds. 


UpperBound 
int UpperBound() const; 
Returns the array's upper peundary 


TStatic class 7 a _ statics 


A TStatic is an interface object that represents a static text interface element. Static 
elements consist of text or graphics that the user does not change. An application, 
however, can modify the static control. You must use a TStatic object, for example, to 
create a static control that's used to display a text label such as a copyright notice in a 
parent TWindow. TStatic can also be used to make it easier to modify the text of static 
controls in TDialogs. See the sample program in the EXAMPLES\ en 
STATIC directory for an example of a static control. 


Public data members 


TextLen 

uint TextLen; | 
TextLen holds the size of the text buffer for static controls. The number of characters that 
can actually be stored in the static control is one less than TextLen because of the null 
terminator on the string. TextLen is also the number of bytes transferred by the Transfer 
member function. 
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Public constructors 


Constructors 
TStatic(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, uint textLen = 0, 

TModule* module = 0); 
Constructs a static control object with the supplied parent window (parent), control ID 
(Id), text (title), position (x, y) relative to the origin of the parent window's client area, 
width (w), height (h), and default text length (textLen) of zero. By default, the static 
céntrol is visible upon creation and has left-justified text. (set to WS_CHILD | 
WS_VISIBLE | WS_GROUP | SS_LEFT.) Invokes a TControl constructor. You can 
change the default style of the static control by via the control object's constructor. 


TStatic(TWindow* parent, int resourceld, uint textLen = 0, TModule* module = 0); 
Constructs a TStatic object to be associated with a static control interface control of a 
TDualog. Invokes the TControl constructor with similar parameters then sets TextLen to 


_ textLen. Disables the data transfer mechanism by calling DisableTransfer. The resourceld 


parameter must correspond to a static control resource that you define. 
See also TControl::TControl 


Public member functions 


Clear 
virtual void Clear(); 
Clears the text of the associated static control. 


GetText 

int GetText(char far* str, int maxChars); 

Retrieves the static control's text, stores it in the str argument of maxChars size, and 
returns the number of characters copied. 


GetTextLen 
int GetTextLen(); 
Returns the length of the static control's text. 


SetText | 
void SetText(const char far* str); 
Sets the static control's text to the string supplied in str. 


Transfer 

uint Transfer(void* buffer, TTransferDirection direction); 

Transfers TextLen characters of text to or from a transfer buffer pointed to by buffer. If 
direction is tdGetData, the text is transferred to the buffer from the static control. If 
direction is tdSetData, the static control's text is set to the text contained in the transfer 
buffer. Transfer returns TextLen, the number of bytes stored in or retrieved from the 
buffer. If direction is tdSizeData, Transfer returns TextLen without transferring data. 
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Protected member functions | 


EvSize oe 

void EvSize (uint sizeType, TSize& size); 

Overrides TWindow's virtual function. When the static control is resized, EvSize ensures 
it's also repainted. 


GetClassName 

virtual char far* GetClassName(); 

Returns the name of TStatic's registration class (STATIC), or returns STATIC_CLASS if 
BWCC is enabled. 


Response table entries 


TStatus class | except.h 


Used primarily for backward compatibility with previous versions of ObjectWindows, 
TStatus is used by TModule and TWindow to indicate an error in the initialization of an 
interface object. If Status is set to a nonzero value, a TXCompatibility exception is thrown. 


See also 
TModule::Status, TWindow: eiatis 


Public constructor 


Constructor 
TStatus(); 
Constructs a TStatus object and initializes the status code to 0. 


Public data members 


operator = 
TStatus& operator =(int statusCode); 
Sets the status code and throws a TX Compatibility exception. 


operator int() 
operator int() const; 
Returns the status code. 
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TStatusBar class statusba.h 


TStatusBar provides support for status bars, inserted gadgets, hint text, and keyboard 
modes. In contrast to plain message bars, status bars provide several display options. 
ObjectWindows status bars let you include multiple text gadgets (the text on the left of 
the status bar) and different border styles. You can also reserve space for mode 
indicators (the text that displays the program's current state, such as extended selection 
(of keys and other modes), CapsLock, NumLock, ScrollLock, Overtype, and macro recording). 
By default, ObjectWindows uses these virtual key codes and displays the following 
strings for the indicated enabled modes: 


Mode  -—=—__s~Virtualkeycode —_— Text displayed 
oe De ee eee 
CapsLock VK_CAPITAL CAPS 
NumLock VK_NUMLOCK NUM 
ScrollLock VK_SCROLL SCRL 
Overtype VK_INSERT OVR 
Macro recording REC 


TStatusBar creates text gadgets for the mode indicators you request and adjusts the 
spacing between mode indicators. The TSpacing struct stores spacing and layout unit 
constraints. 


Like other control bars, the status bar is constructed and destroyed at the same time as 
its parent's window, but this is not a required procedure. 


The following program statements show how to construct a status bar and insert it at 
the bottom of the window. 


TStatusBar* sb = new TStatusBar(0, TGadget_Recessed, 
TStatusBar_CapsLock | TStatusBar_NumLock | TStatusBar_Overtype) ; 

frame->Insert (*sb, TDecoratedFrame: :Bottom) ; 

MainWindow = frame; 


See the MDIFILE.CPP sample program on your distribution disk for an example of how 
to create a window with a status bar. 


Type definitions 


TModelndicator 

enum TModelndicator {ExtendSelection = 1, CapsLock = 1 << 1, NumLock = 1 << 2, ScrollLock = 1 << 3, 
Overtype = 1 << 4, RecordingMacro = 1 << 5}: 

Enumerates the keyboard modes. By default, these are arranged horizontally on the 

status bar from left to right. Sets the extended selection, Caper eO NumLock, ScrollLock, 

Overtype, and recording macro indicators. 
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| Public constructor | 


Constructor 

_ TStatusBar(TWindow* parent = 0, TGadget -TBorderStyle CsaaStiex TGadget_Recessed, 

uint modelndicators = 0, TFont* font = new TGadgetWindowFont, TModule* module = 0); 

Constructs a TStatusBar object in the parent window and creates any new gadgets and 
mode indicator gadgets. Sets BorderStyle to borderStyle, ModeIndicators to modeIndicators, 
and NumModeIndicators to 0. borderStyle can be any one of the value of theBorderStyle 
enum (for example, plain, raised, recessed, or embossed). The parameter mode 
indicators can be one of the values of the TModelIndicator enum, such as CapsLock, 
NumLock, ScrollLock, or Overtype. The parameter font points to a font object that 
contains the type of fonts used for the gadget window. The parameter, module, which 
defaults to 0, is passed to the base TWindow’s constructor in the module parameter. Sets 
the values of the margins and borders depending on whether the gadget is raised, 
recessed, or plain. 


Public member functions 


GetModelndicator 
bool GetModelndicator(TModelndicator i) const; 
Returns the current status bar mode indicator. 


Insert 
void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0); | 
Inserts the gadget (objects derived from class TGadget) in the status bar. By default, the 
new gadget is placed just after any existing gadgets and to the left of the status mode 
indicators. For example, you can insert a painting tool or a happy face that activates a 
recorded macro. 


operator|] 
TGadget* operator[](uint index); 
Returns a gadget at a given index, but cannot access mode indicator gadgets. 


SetModelndicator 

void SetModelndicator(TModelndicator, bool state); 

Sets TModelIndicator to a given text gadget and set the status (on, by default) of the mode 
indicator. For the mode indicator to appear on the status bar, you must specify the mode 
when the window is constructed. — 


Seealso TStatusBar::TModelndicator 


SetSpacing 

void SetSpacing(TSpacing& spacing); | 

Uses the TSpacing values to set the spacing to be used between mode indicator gadgets. 
TSpacing sets the status-bar margins in layout units. Typically, the message indicator 
(the leftmost text gadget) is left-aligned on the status bar and the other indicators are 
right-aligned. See TLayoutMetrics for an detailed explanation of layout units and 
constraints. 


struct TSpacing { 
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TMargins::TUnits Units; 

int Value; 

TSpacing() {Units = TMargins::LayoutUnits; Value = 0;} 
}; | 


Seealso TStatusBar::TModelIndicator 


ToggleModelndicator 
void ToggleModelndicator(TModelndicator); 
Toggles the ModeIndicator. 


Protected data members 


BorderStyle 

TGadget::TBorderStyle BorderStyle; 

One of the enumerated border styles—none, plain, raised, recessed, or embossed—used 
by the mode indicators on the status bar. 


Modelndicators 

uint Modelndicators; 

The ModelIndicators bit field indicates which mode indicators have been created for the 
status bar. 


_ ModelndicatorState 

uint ModelndicatorState; 

Specifies the mode of the status bar. This can be any one of the values of TModeIndicator 
enum such as CapsLock, NumLock, ScrollLock, Le RecordingMacro, or 
ExtendSelection. 


NumModelindicators 
uint NumModelndicators; 
Specifies the number of mode indicators, which can range from 1 to 5. 


Spacing 
TSpacing Spacing; 
Specifies the spacing between mode indicators on the status bar. 


Protected member functions 


IdleAction 

bool IdleAction(long); 

If more than one application is running, TStatusBar calls IdleAction instead of 
PreProcessMsg to check the state of the NumLock, CapsLock, or ScrollLock keys and to 
update the mode indicators if they do not reflect the current status of these keys. 


Seealso TStatusBar::PreProcessMsg 


PositionGadget 
void PositionGadget(TGadget* previous, TGadget* next, TPoint& point) 
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Determines the position of the new gadget in relation to any previously existing gadgets 
and uses the Pixels, LayoutUnits, and BorderUnits fields of TMargins to determine the 
amount of spacing to leave between the mode indicators. 


PreProcessMsg | 

bool PreProcessMsg(MSG& msg); 
Overrides TWindow::PreProcessMsg to process keyboard messages and update the mode 
indicators when the NumLock, CapsLock, or ScrollLock keys are pressed. 


Seealso TStatusBar::IdleAction 


TStorageDocument class 7 “stgdoc.h 


rena en er ni tan ERE re Ut ONO RRO ren At NNN at een er te een ner A MARR AN HNNNONE 


Derived from TDocument, TStorageDocument supplies functionality that supports OLE's 
compound file structure. A compound file structure is a fileemanagement system that 
stores files in a hierarchical structure within a root file. This storage structure is 
analagous to the directory or folder and file scheme used on a disk, except that a 
directory is called a storage and a file is called a stream. 


In addition, TStorageDocument provides support for OLE's compound document 
mechanism. A compound document can store many different kinds of embedded 
objects, for example, spreadsheets as well as bitmaps. 


Basically, TStorageDocument supports having a document read and write its own 
storage. In order to provide this functionality, TStorageDocument overrides several 
virtual methods from TDocument and, following TDocument's strategy, also applies 
property lists both to documents and to their views. In this way, documents can use 
these attributes to read files in from storage and write files out to storage 


Messages are sent to the application, which queries the properties in order to determine 
how to process the document or view. Each derived class must implement its own 
property attribute types-either string or binary data. 


See also 
TDocument, TOleDocument 


Type definitions 

TStgDocProp | 

enum TStgDocProp {PrevProperty, CreateTime, ModifyTime, AccessTime, StorageSize, IStoragelnstance, 
NextProperty}; | 

Enumerates the following constants that define the document's properties: 


PrevProperty Should always have a value of TDocument::NextProperty — 1. This is the initial value in 


any document's property list. 
CreateTime The time the file is created. 


ModifyTime The time the file is modified. 
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AccessTime The last time the file was accessed. 
StorageSize The size of the storage buffer. 


IStorageInstance The storage instance for the document. 
NextProperty The final value for any document's list of properties. 


Public constructor and destructor 


Constructor 

Constructor TStorageDocument(TDocument* parent = 0): TDocument(parent), Storagel(0), OpenCount(0), 
CanRelease(false); 

Constructs a TStorageDocument object with the specified TDocument parent window. 

Sets the data members Storagel and OpenCount to 0. Sets CanRelease to false. Later, the 

member function ReleaseDoc sets this flag to true so that the document can be closed. 


Destructor 
~TStorageDocument(); 
Destroys a TStorageDocument object. 


Public member functions 


Close 

bool Close(); 

Releases the [Storage if CanRelease is true. (Cankelease is set to true when ReleaseDoc is 
called.) Before closing the document, Close checks any child documents and tries to close 
them. | 


Seealso TStorageDocument::Open, TStorageDocument::ReleaseDoc, TOutStream, 
ofxxxx document open enum 


Commit 

bool Commit(bool force = false); 

Saves the current data to storage. When a file is closed, the document manager calls 
either Commit or Revert. If force is true, all data is written to storage. TDocument's Commit 
checks any child documents and commits their changes to storage also. Before the 
current data is saved, all child documents must return true. If all child documents return 
true, Commit flushes the views for any operations that occurred since the last time the 
view was checked. Once all data for the document object is updated and saved, Commit 
returns true. 


CommitTransactedStorage 
bool CommitTransactedStorage(); 


If a file is opened or created in transacted mode, call CommitTransactedStorage to commit 
a document to permanent storage. By default, a document uses transacted instead of 
direct storage. With transacted storage, a document written to [Storage is only temporary 
until it is committed permanently. If a compound file is opened or created in direct 
mode, then CommitTransactedStorage does not need to be called. 


Chapter 2, ObjectWindows library reference 417 


po oleae acumen class. 


FindProperty ; 
int FindProperty(const char far* name); 

- Gets the property index, given the property name. Returns the integer index eae: 
that corresponds to the name. If the name isn't found in the list of properties, returns 0. 


See also pfxxxx property attribute constants 


GetProperty 

int GetProperty(int index, void far* dest, int textlen=0); 

Returns the total number of properties for this storage document, where index is the 
property index, dest contains the property data, and textlen is the size of the property 
array. If textlen is 0, the property data is aes as ea data; otherwise, the property 
data is returned as text data. 


See also pfxxxx property attribute constants, TStorageDocument::SetProperty 


~ GetStorage 
IStorage* GetStorage(); 
Returns the document's root Storage. 


Seealso TStorageDocument::SetStorage 


— InStream 
TinStream* InStream(int omode, const char far* strmid=0); 
Provides an input stream for the TStorageDocument object. Returns a pointer to a 
TInStream object. The parameter omode contains a combination of the document open 
and sharing modes (for example, ofReadWrite) defined in docview.h. The strmld 
parameter is used for documents that support named streams. 


Seealso TStorageDocument::OutStream, TInStream, ofxxxx document open enum 


IsOpen 

bool IsOpen(); 

Checks to see if the storage document has any [Storage created. If there is no storage, 
IsOpen returns false; otherwise, it returns true. 


Open 

bool Open(int omode, const char far* name): 

Opens or creates a document based on [Storage. The name parameter specifies the name 
of the document, if any, to open. The omode parameter contains a combination of the 
document open and sharing modes (for example, ofReadWrite) defined in docview.h. 


Seealso TStorageDocument::Close, TOutStream, ofxxxx document open enum 


OpenHandle 

virtual boo! OpenHandle(int omode, HANDLE hGlobal); | 
OpenHandle writes data to a memory block. OpenHandle first creates an [LockBytes (an 
OLE2 interface that implements reading, writing, and locking a series of bytes in a file) 
interface on the global handle and then creates an [Storage based on the ILockBytes 
interface. The parameter omode contains a combination of the document open and 
sharing modes (for example, ofReadWrite) defined in docview.h. 


See also ofxxxx document open enum 
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OutStream 

TOutStream* OutStream(int omode, const char far* strmld=0); 

Provides an output stream for a particular storage medium. Returns a pointer to a 
TOutStream. The parameter omode contains a combination of the document open and 
sharing modes (for example, ofReadWrite) defined in docview.h. The strmld parameter is 
used for documents that support named streams. 


Seealso TStorageDocument::InStream, TOutStream, ofxxxx document open enum 


PropertyCount 

int PropertyCount(); 

Gets the total number of properties for the TStorageDocument object. Returns 
NextProperty —1. 


See also pfxxxx property attribute constants 


PropertyFlags 

int PropertyFlags(int index): 

Returns the attributes of a specified property given the index of the property whose 
attributes you want to retrieve. 


See also pfxxxx property attribute constants 


PropertyName 
const char* PropertyName(int index); | 
Returns the name of the property given the index value. 


See also pfxxxx property attribute constants 


ReleaseDoc 
virtual boo! ReleaseDoc(); 
Releases the storage for the document and closes the document. 


Revert 

bool Revert(bool clear = false); 

Performs the reverse of Commit and cancels any changes made to the storage document 
since the last commit. If clear is true, data is not reloaded for views. Revert also checks all 
child documents and cancels any changes if all children return true. When a file is 
closed, the document manager calls either Commit or Revert. Revert returns true if the 
revert operation is successful. 


SetDocPath 
bool SetDocPath(const char far* path); 
Sets the document path for the Open and Save file operations. 


SetProperty 

bool SetProperty(int index, const void far* src); 

Sets the value of the property, given the index of the property, and src, the data type 
(either binary or text) to which the property must be set. | 


Seealso pfxxxx property attribute constants, TStorageDocument::GetProperty 
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SetStorage 
IStorage* SetStorage(IStorage* stg); 
Attaches an [Storage pointer (stg) to this document. 


Seealso TStorageDocument::GetStorage, TStorageDocument::Storagel 


Protected data members 


- ThisOpen 
int ThisOpen; 
Holds the actual mode bits used for opening the storage. The mode bits determine how 
the file is opened: for example, read only, read and write, and so on. 


Seealso ofxxxx document open enum 


Storagel 
IStorage* Storagel; 
Holds the current [Storage instance. (If no storage is open, Storagel is 0.) 


Seealso T'StorageDocument::GetStorage, TStorageDocument::SetStorage 


TStream class docview.h 


An abstract base class, TStream provides links between streams and documents, views, 
and document files. 


Public destructor 


Destructor 

~TStream(); 

Closes the stream. Derived classes generally close the document if it was opened 
especially for this stream. 


Public member functions 


GetDocument 
TDocument& GetDocument(); 
Returns the current document open for streaming. 


GetOpenMode 

int GetOpenMode(); | 

Gets mode flags used when opening document streams. For example, the stream can be 
opened in ofRead mode to allow reading, but not changing (writing to) the file. 


See also ofxxxx document open enum 


GetStreamName 
const char far* GetStreamName(); 
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Gets the name of the stream used for opening the document. 


Protected data members 


Doc 
TDocument& Doc; 
Stores the document that owns this stream. 


NextStream 
TStream* NextStream; 
Points to the next stream in the list of active streams. 


Protected constructor 


Constructor 

TStream(TDocument& doc, const char far* name,int mode); 

Constructs a TStream object. doc refers to the document object, name is the user-defined 
name of the stream, and mode is the mode used for opening the stream. 


Seealso TInStream, TOutStream, ofXXXX document open enum, shXXXX document 
sharing enum 


TStringLookupValidator class validate.h 


Derived from TLookupValidator, TStringLookup Validator is a streamable class. A 
TStringLookup Validator object verifies the data in its associated edit control by searching 
through a collection of valid strings. You can use string-lookup validators when your 
edit control needs to accept only members of a certain set of strings. 


Public constructor and destructor 


Constructor 

TStringLookupValidator(TSortedStringArray* strings); 

Constructs a string-lookup object by first calling the constructor inherited from 
TLookup Validator and then setting Strings to strings. 


Destructor 
~TStringLookupValidator(); 
This destructor disposes of a list of valid strings by calling NewStringList and then 
disposes of the string-lookup validator object by calling the Destructor inherited from 
TLookup Validator. 


Public member functions 


Error 
void Error(); 
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Overrides TValidator’s virtual function and displays a message box indicating that the 
_ typed string does not match an entry in the string list. 


Seealso TValidator::Error 


Lookup 

bool Lookup(const char far* str); 

Overrides TLookupValidator’s virtual function. Returns true if the string passed i in str 
matches any of the strings. Uses the search method of the string collection to determine if 
str is present. 


~ See also TLookupValidator: :Lookup 


NewStringList 

void NewStringlist(TSortedStingArray* strings); 

Sets the list of valid input string for the string-lookup validator. Disposes of any existing 
ee list and then sets Strings to strings. | 


Protected data member 


Strings 

TSortedStringArray* Strings; | 

Points to a string collection containing all the valid strings the user can type. If Strings is 
NULL, all input is validated. | 


TSystemMenu class menu.h 
TSystemMenu creates a system menu object that then becomes the existing system menu. 
Public constructor 
Constructor 


TSystemMenu(HWND wna, bool revert = false); 
Constructs a system menu object. If revert is true, then the menu created is a default 
system menu. Otherwise, it is the menu currently in the window. 


Seealso TPopupMenu::TPopupMenu 


Derived from TGadget, TTextGadget is a text gadget object. When you construct a text 
gadget, you must specify how many characters you want to reserve space for and how 
the text should be aligned horizontally. The inner boundaries of the text gadget are 
computed by multiplying the number of characters by the maximum character width. 
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Public constructor and destructor 


Constructor 

TTextGadget(int id = 0, TBorderStyle = Recessed, TAlign = Left, uint numChars = 10, const char* text = 0); 
Constructs a TTextGadget object with the specified ID, border style, and alignment. Sets 
Margins.Left and Margins.Right to 2. Sets Text and TextLen to 0. 


Destructor 
~TTextGadget(); 
Destroys a TTextGadget object. 


Public member functions 


GetText 
char* GetText(); 
Returns the text for the gadget. 


SetText 

void SetText(const char* text); 

If the text stored in Text is not the same as the new text, SetText deletes the text stored in 
Text. Then, it sets TextLen to the length of the new string. If no text exists, it sets both Text 
and. TextLen to 0 and then calls Invalidate to invalidate the rectangle. 


Protected data members 


Align 
TAlign Align; 
Text alignment attribute—left-, center-, or right-aligned. 


NumChars 
uint NumChars; 
Holds the number of text characters. 


Text 
char* Text; 
Points to the text for the gadget. 


TextLen 
uint TextLen:; 
Stores the length of the text. 


Protected member functions 


GetDesiredSize 

void GetDesiredSize(TSize &size); | 
If shrink-wrapping is requested, GetDesiredSize returns the size needed to accommodate 
the borders, margins, and text; otherwise, if shrink-wrapping is not requested, it returns 
the gadget's current width and height. 
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See also TGadget: GetDesiredSize 


invalidate 

void Invalidate(); 

Calls TGadget: -GetlninerRect to compute the area of fhe! text for the gadget and then > 
TGadget::InvalidateRect to invalidate the rectangle in the parent window. 


Seealso TGadget::GetInnerRect, TGadget::Invalidate 

Paint 

void Paint(TDC& dc); 

Calls TGadget::PaintBorder to paint the border. Calls TGadget::GetInnerRect to calculate 
the area of the text gadget's rectangle. If the text is left-aligned, Paint calls 
dc.GetTextExtent to compute the width and height of a line of the text. To set the 
background color, Paint calls dc.GetSysColor and sets the default background color to 
face shading (COLOR_BTNFACE). To set the button text color, Paint calls 
dc.SetTextColor and sets the default button text color to COLOR_BTNTEXT. To draw the 
text, Paint calls dc.ExtTextOut and passes the parameters ETO_CLIPPED (so the text is 
clipped to fit the rectangle) and ETO_OPAQUE (so the rectangle is filled with the 
current background color). 


Seealso TGadget::Paint 


Type definitions gadgetwi.h 


TTileDirection 

enum TTileDirection{Horizontal, Vertical}: 

Enumerates the two directions the gadget can be tiled. TGadget Window:: TileGadgets 
actually tiles the gadgets in the direction requested. 


Seealso TGadgetWindow::Direction, TGadgetWindow::TileGadgets 


TAlign 

enum TAlign {Left, Center, Right}; 

Enumerates the text-alignment attributes. Left aligns the text at the left edge of the 
bounding rectangle. Right aligns the text at the right edge of the bounding rectangle. 
Center aligns the text horizontally at the center of the bounding rectangle. 


TTinyCaption class tinycapt.h 


Derived from TWindow, TTinyCaption is a mix-in class that handles a set of non-client 
events to produce a smaller caption bar for a window. Whenever it displays the caption 
bar, TTinyCaption checks the window style and handles the WS_SYSMENU, 
WS_MINIMIZEBOX, WS_MAXIMIZEBOX display attributes. Thus, you can use 
TTinyCaption to set the attributes of the tiny caption bar before enabling the caption. For 
example, 


Attr.Style = WS_POPUP | WS_BORTER | WS_SYSVENU | WS _MINIMIZERDX | WS_MAXIMIZEBOX ; 


424 ObjectWindows Reference Guide 


TTinyCaption class 


TTinyCaption provides functions that let you manipulate frame types, border styles, and 
menus. You can adjust the height of the caption bar or accept the default height, which 

is about one-half the height of a standard caption bar. If you set CloseBox to true, then the 
window will close when you click the close box instead of displaying the system menu. 


The sample program OWLCMD.CPP on your distribution disk displays the following 
tiny caption bar: 


Close Box List Box Minimize Box 


CABORLSE ROL wLESShIPLES 


If you are using TTinyCaption as a mix-in class that does partial event handling, call the 
DoXxxx function in the mix-in class (instead of the EvuXxxx function) to avoid 
duplicating default processing. The following example from OWLCMD.CPP (a sample 
program on your distribution disk) illustrates this process: 


void TMyFrame::EvSysCommand(uint cmdType,TPoint& p) 


{ 
if (TTinyCaption: :DoSysCommand(cmdType, p) == esPartial) 
FrameWindow: :EvSysCommand(cmdType, p); 


The TFLoatingFrame class can be used with TTinyCaption to produce a close box. See the 
sample programs OWLCMD.CPP and MDIFILE.CPP on your distribution disk for 
examples of how to use TTinyCaption. 


Protected data members 


Border 
TSize Border; 
Thin frame border size for dividers. 


CaptionFont 
TFont* CaptionFont; 
Font used for the text in the tiny caption bar. 


CaptionHeight 
int CaptionHeight; 
Height of the caption bar. 


CloseBox 
bool CloseBox; 
If true, the window will close when the close box is clicked. 


Downhit 
uint DownHit; 
Location of mouse-button press or cursor move. 


Frame | 
TSize Frame; 
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| Actual left and right ad and bottom dimensions of the caption bar. 


IsPressed 
bool IsPressed; 
Is true if a mouse button is pressed. 


TCEnabled 
bool TCEnabled; | 
Is true if the tiny caption bar is displayed. 


WaitingForSysCmd 
bool WaitingForSysCmd; 
_ Is true if TTinyCaption is ready to receive system messages. 


Protected constructor and destructor 


Constructor 

TTinyCaption(); 

Constructs a TTinyCaption object attached to the given parent window. Initializes the 
caption font to 0 and TCEnabled to false so that the tiny caption bar is not displayed 
automatically. 


Destructor 
~TTinyCaption(); 
Destroys a TTinyCaption object and deletes the caption font. 


Protected member functions 


DoCommand 

TEventStatus DoCommand(uint id, HWND hWndCil, uint notifyCode, LRESULT& evRes); 

Displays the system menu using ::TrackPopup so that TTinyCaption sends 
WM_COMMAND instead of WM_SYSCOMMAND messages. If a system menu 
command is received, it's then transformed intoa WM_SYSCOMMAND message. If the 
tiny caption bar is false, DoCommand returns esPartial. 


Seealso T'TinyCaption::EvCommand, TEventStatus enum 


DoLButtonUp 

TEventStatus DoLButtonUp(uint hitTest, TPoint& screenPt); 

Releases the mouse capture if the caption bar is enabled and a mouse button is pressed. 
Sets hitTest, indicating the mouse button has been pressed. Captures the mouse message 
and repaints the smaller buttons before returning esComplete. 


Seealso TTinyCaption::EvLButtonUp 


DolMouseMove 
TEventStatus DoMouseMove(uint hitTest, TPoint& eae 
Returns TEventStatus. 
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DoNCActivate 

TEventStatus DoNCActivate(bool active, bool& evRes); 

If the tiny caption is not enabled or is iconic, returns esPartial. Otherwise, repaints the 
caption as an active caption and returns esComplete. 


Seealso TTinyCaption::EvNCActivate 


DoNCCalcSize 

TEventStatus DoNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far&calcSize, uint& evRes); 

If the caption bar is not enabled or is iconic, returns esPartial. Otherwise, calculates the 
dimensions of the caption and returns esComplete. 


Seealso TTinyCaption::EvVNCCalcSize 


DoNCHitTest 

TEventStatus DoNCHitTest(TPoint& screenPt, uint& evRes); 

If the caption bar is not enabled, returns esPartial. Otherwise, sends a message to the 
caption bar that the mouse or the cursor has moved, and returns esComplete. 


Seealso TTinyCaption::EvNCHitTest 


DoNCLButtonDown 

TEventStatus DoNCLButtonDown(uint hitTest, TPoint& screenPt); 

If the caption bar isn't enabled, returns esPartial. Otherwise, determines if the user 
released the button outside or inside a menu, and returns esComplete. 


Seealso T'TinyCaption::EVNCLButtonDown 


DoNCPaint 

TEventStatus DoNCPaint(); 

If the caption bar isn't enabled or is iconized, returns esPartial. Otherwise, gets the focus, 
paints the caption, and returns esPartial, thus indicating that a separate paint function 
must be called to paint the borders of the caption. 


Seealso 9 T'TinyCaption::EVNCPaint 


DoSysCommand 

TEventStatus DoSysCommand(uint cmdType, TPoint& p); 

If the caption bar isn't enabled, returns esPartial. If the caption bar is iconized and the 
user clicks the icon, calls DoSysMenu to display the menu in its normal mode and 
returns esComplete. 


Seealso 9 TTinyCaption::EvSysCommand 


DoSysMenu 

void DoSysMenu; 

Gets the system menu and sets up menu items. DoSysMenu is also responsible for 
displaying and tracking the status of the menu. 


EnableTinyCaption 

void EnableTinyCaption(int ch=58, bool closeBox=false); 

Activates the tiny caption bar. By default, EnableTinyCaption replaces the system 
window with a tiny caption window that doesn't close when the system window is 
clicked. If the closeBox argument is true, clicking on the system menu will close the 
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window instead of bringing up the menu. You can use EnableTinyCaption to hide the 
window if you are using a tiny caption in a derived class. To diminish the tiny caption 
bar, try the following values: 


EnableTinyCaption(30, true); 
Or, to maximize the tiny caption bar, use these values: - 


EnableTinyCaption(48, true); 


EvCommand 

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode); 

EvCommand provides extra processing for commands, but lets the focus window and its 
parent windows handle the command first. 


Seealso TTinyCaption::DoCommand 


- EvLButtonUp 
void EvLButtonUp(uint hitTest TPoint& screenPt); 
Responds to a mouse button-up message by calling DoLButtonUp. If DoLButtonUp 
doesn't return IsComplete, EvLButtonUp calls TWindow::EvLButtonUp. 


Seealso 9 TTinyCaption::DoLButtonUp 


EvMouseMove 

void EvMouseMove(uint hitTest, TPoint& screenPt); 

Responds to a mouse-move message by calling DoMouseMove. If DoMouseMove doesn't 
return IsComplete, EoMouseMove calls TWindow::EvMouseMove. 


Seealso TTinyCaption:: DoMouseMove 


EvNCActivate 

bool EvNCActivate(bool active); 

Responds to a request to change a title bar or icon by calling DoNCActivate. If 
DoNCActivate doesn't return esComplete, EoNCActivate calls TWindow::EvNCActivate. 


Seealso ‘'TinyCaption:: DoNCActivate 
EvNCCalcSize | 
uint EVNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far& calcSize); 


Responds to a request to change a title bar or icon by calling DoNCActivate. If 
DoNCActivate doesn't return esComplete, EoNCActivate calls TWindow::EvNCActivate. 


Calculates the size of the command window including the caption and border so that it 
can fit within the window. 


Seealso TTinyCaption:: DoNCActivate 


EvNCHitTest 

uint EvNCHitTest(TPoint& screenPt); 

Responds to a cursor move or press of a mouse button by calling DoNCHitTest. If 
DoNCHitTest doesn't return esComplete, EoNCHitTest calls TWindow::EvNCHitTest. 


Seealso ‘T'TinyCaption:: DoNCHitTest 
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EvNCLButtonDown 

void EvNCLButtonDown(uint hitTest, TPoint& screenPt); 

Responds to a press of the left mouse button while the cursor is within the nonclient 
area of the caption bar by calling DoNCLButtonDown. If DoNCLButtonDown doesn't 
return esComplete, EvNCLButtonDown calls TWindow::EvNCLButtonDown. 


Seealso T'TinyCaption:: DoNCLButtonDown 


EvNCPaint 

void EvNCPaint(); 

Responds to a request to change a title bar or icon. Paints the indicated device context or 
display screen and does any special painting required for the caption. 


Seealso ‘T’TinyCaption:: DoNCActivate 


EvSysCommand 

void EvSysCommand(uint cmdType, TPoint& p); 

Responds toa WM_SYSCOMMAND message by calling DoSysCommand. If 
DoSysCommand returns esPartial, EvSysCommand calls TWindow::EvSysCommand. 


Seealso TTinyCaption::DoSysCommand 


GetCaptionRect 
TRect GetCaptionRect(); 
Gets the area of the caption for changing or repainting. 


Seealso T'TinyCaption::PaintCaption 


GetMaxBoxRect 
TRect GetMaxBoxRect(); 
Returns the size of the maximize box rectangle. 


Seealso T’TinyCaption::PaintMaxBoxRect 


GetMinBoxRect 
TRect GetMinBoxRect(); 
Returns the size of the minimize box rectangle. 


Seealso J'T'inyCaption::PaintMinBoxRect 


GetSysBoxRect 
TRect GetSysBoxRect(); 
Returns the size of the system box rectangle. 


See also ‘’TinyCaption::PaintSysBoxRect 


PaintButton 
void PaintButton(TDC& dc, TRect& boxRect, bool pressed); 
Paints a blank button. 


PaintCaption 

void PaintCaption(bool active); 

Calls dc.SelectObject to select the given rectangle and dc.PatBlt to paint the tiny caption 
bar using the currently selected brush for this device context. 
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PaintCloseBox 

void PaintCloseBox(TDC& dc, TRect& boxRect, bool pressed); 

Paints a close box on the tiny caption bar. You can override the default box if you want 
to design your own close box. 


Seealso T'TinyCaption: GetSysBoxRect 
PaintMaxBox 


void PaintMaxBox(TDC& dc, TRect& boxRect, bool pressed); 
Paints a maximize box on the tiny caption bar. 


Seealso ‘’TinyCaption::GetMaxBoxRect 


PaintMinBox 
void PaintMinBox(TDC& dc, TRect& boxRect, bool pressed); 
Paints a minimize box on the tiny caption bar. 


Seealso § ‘[’TinyCaption::GetMinBoxRect 


PaintSysBox - 
void PaintSysBox(TDC& dc, TRect& boxRect, bool pressed); 
Paints the system box. 


Seealso § ‘’TinyCaption::GetSysBoxRect 


Response table entries 


~ EV_WM_NCACTIVATE EvNCActivate 
EV_WM_NCCALCSIZE EvNcCalcSize 
EV_WM_NCHITTEST ~  EvNcHitTest 
EV_WM_NCPAINT __. EvNcPaint 
EV_WM_NCLBUTTONDOWN EvNclButtonDown 
EV_WM_LBUTTONUP EvLButtonUp 
EV_WM_MOUSEMOVE EvMouseMove 
EV_WM_ SYSCOMMAND EvSysCommand 

TToolBox class toolbox.h 


Derived from TGadgetWindow, TToolBox arranges gadgets in a matrix in which all 
columns are the same width (as wide as the widest gadget) and all rows are the same 
height (as high as the highest gadget). 


You can specify exactly how many rows and columns you want for your toolbox, or you 
can let TToolbox calculate the number of columns and rows you need. If you specify 
AS_MANY_AS_ NEEDED, the TToolBox calculates how many rows or columns are 
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needed based on the opposite dimension. For example, if there are twenty gadgets, and 
you requested four columns, your matrix would have five rows. 


Public constructor 


_ Constructor 
TToolBox(TWindow* parent, int numColumns = 2, int numRows = AS MANY AS NEEDED, 

TTileDirection direction = Horizontal, TModule* module = 0); 
Constructs a TToolBox object with the specified number of columns and rows and tiling 
direction. Overlaps the borders of the toolbox with those of the gadget and sets 
ShrinkWrapWidth to true. 


Public member functions 


GetDesiredSize 

void GetDesiredSize(TSize& size); 

Overrides TGadget's GetDesiredSize function and computes the size of the cell by calling 
GetMargins to get the margins. 


Seealso TGadgetWindow::GetDesiredSize 


Insert 
void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0); 
Overrides T'Gadget's Insert function and tells the button not to notch its corners. 


Seealso TGadgetWindow::Insert 


LayoutSession 

void LayoutSession(); 

Called when a change occurs in the size of the margins of the toolbox or size of the 
gadgets, LayoutSession gets the desired size and moves the window to adjust to the 
desired change in size. 


SetDirection | 
virtual void SetDirection(TTileDirection direction); 
Sets the direction of the tiling—either horizontal or vertical. 


Protected data members 


NumColumns 
int NumColumns; 
Contains the number of columns for the toolbox. 


NumRows 
int NumRows; 
Contains the number of rows for the toolbox. 
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Protected member function 


TileGadgets 

TRect TileGadgets; | | 

Tiles the gadgets in the direction requested (horizontal or vertical). Derived classes can 
adjust the spacing between gadgets. 


Seealso TGadgetWindow: TileGadget 


TTransferDirection enum oe window. 


enum TTransferDirection {tdGetData, tdSetData, tdSizeData}; 
TTransferDirection enum describes the following constants, which the transfer function 
uses to determine how to transfer data to and from the transfer buffer. 


tdGetData Retrieve data from the class. 
tdSetData Send data to the class. 
tdSizeData Return the size of data transferred by the class. 


Seealso TWindow::Transfer, TWindow::TransferData 


TUlHandle class _ uihandle .h 


TUlHandle manages and draws various kinds of UI handles, including hatched border 
handles, and resizing grapples (small squares that appear along the edges) ona 
rectangle. You can use this class to create a hatched border that encloses various kinds of 
drawing objects you want to manipulate. 


With the help of this class, you can create an application that lets you: 


¢ Resize the shape of the rectangle by pointing to and grabbing one of the grapples on 
the border. 


¢ Move the entire rectangle by clicking in the middle of the rectangle. 


Although, by default, a hatched border with eight grapples is created, you can vary the 
existence of the grapples as well as the pattern of the border. You can also draw a 
dashed frame enclosing a rectangle or draw a rectangle filled with hatch marks. 
THatch8x8Brush contains brushes you can use to draw the hatched border. 


TUIHandle uses the enum TWhere to return the area where the user points and clicks the 
mouse (referred to as a hit aren). 


432 ObjectWindows Reference Guide 


TUIHandle class 


The following diagram displays a UI handle and identifies several small square 
grapples where hit testing occurs. 


Top Left Top Center Top Right 


AAA AAR 


Midcenter, or, Inside if 
InsideSpecial is set 


Mid Left Mid Right 


Mid Center (move area) 


Bottom Left Bottom Center Bottom Right 


The following code from SAMPCONT.CPP sets up a hatched border and UI grapples 
for an OLE2 container application. 


// Do the default rectangle painting. 
TRect r // Insert your rectangle drawing code here. 
// Draw 8 grapples with a border on top of the object. 
TUIHandle handle(r, TUIHandle: :HandlesIn|TUIHandle: eran e8 
| TUIHandle::HatchBorder, 5); 
handle. Paint (dc) ; 
// Insert your code here.. 
// Draw a hatched border. 
TUIHandle handle(r, TUIHandle::HatchBorder, 5); 
handle. Paint (dc); 


See also 
THatch8x8Brush 


Type definitions 


TStyle 

enum TStyle{Handlesin, HandlesOut, Framed, DashFramed, Grapples, HatchBorder, HatchRect, InsideSpecial}; 
Enumerates the style of the border around the rectangle with combinations of the 
following styles: 


‘Select one of the following styles: 


HandlesIn Draw handles inside the rectangle 
HandlesOut Draw handles outside the rectangle 

Select zero or one of the following styles: | : 

Framed Draw a solid frame around the rectangle 
DashFramed | Draw a dashed frame around the rectangle 
Grapples | Draw eight grapples for resizing 
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Select zero or one of the following styles 


HatchBorder a Draw a hatched handle for moving the border 
HatchRect | , _ Draw the entire rectangle filled in with hatch marks 
InsideSpecial | Treat the inside hit area in a special way 


If a hatched border with grapples i is drawn inside a rectangle, it sits within the borders 
of the outer frame of the rectangle. If a hatched border with grapples is drawn outside 
the rectangle, it is drawn outside the boundary of the rectangle's frame. In the latter case, 
the function GetBoundingRect returns a larger rectangle. | 


TWhere 

enum TWhere {TopLeft, TopCenter, TopRight, MidLeft, MidCenter, MidRight, BottomLeft, BottomCenter, 
BottomRight, Outside, Inside}; 

TWhere indicates which one of the grapples or handle was hit. TWherecan contain one of 

the following values: | 


TopLeft The grapple in the top left corner of the border was hit. 

TopCenter The grapple in the top center of the border was hit. 

TopRight 7 The grapple in the top left right corner of the border was hit. 

MidLeft . _ The grapple in the middle of the left border was hit. 

MidCenter The area in the middle of the rectangle was hit. This indicates that either the 
hatched frame was hit or inside, non-special area was hit. 

MidRight The grapple in the middle of the right border was hit. 

BottomLeft The grapple in the left corner of the bottom border was hit. 

BottomCenter . _ The grapple in the center of the bottom border was hit. 

BottomRight The grapple in the right corner of the bottom border was hit. 

Outside The hit area is completely outside the object. 

Inside | The hit area for the grapple is inside the object and InsideSpecial is set. 


The InsideSpecial designation refers to the area inside the rectangle when the hit area 
needs to be treated specially because it might contain text or graphics, for example. 
Normally, if the area inside the rectangle is hit, it means that user wants to move the 
rectangle. However, if there is text inside the rectangle, the user might click on this area 
in order to enter text. This latter situation is referred to as an inside special case. 


The hit area (Where) can be converted to a row and a column by using the following 
ea uatlons: 


Row = Where ee. 
Column = Where mod 3 
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The value of Where ranges from 0 (TopLeft) to 8 (BottomRight) and corresponds to the 
following areas of a rectangle: 


Column 
0 { 2 


Fak MidC MidR 
BottomC | BottomR 


You can then use these values to calculate the movement of the object and to resize the 
object. 


Row 1 


Public constructor 


Constructor 

TUlHandle(const TRect& frame, uint style = Handlesin|Grapples|HatchBorder, int thickness = 5); 
Constructs a TU[Handle object for the specified frame, with eight grapples drawn in a 
hatched border and a default thickness of 5 pixels drawn to the inside. 


Public member functions 


GetBoundingRect 

GetBoundingRect()const; 

GetBoundingRect returns a rectangle with the size adjusted according to the thickness. 
For example, if the handles are outside the rectangle, GetboundingRect returns a larger 
rectangle. The enum . TStyle defines the positions of the handles, that is, whether the 
handles are defined as HandlesIn or HandlesOut. 


GetCursorld 

static uint16 GetCursorld(TWhere where); 

Returns the ID of a standard cursor that's appropriate for use over the location specified 
in the where parameter. 


HitTest 

TWhere HitTest(const TPoint& point)const; 

Compares a given point (point) to various parts of the rectangle. If the hit was outside 
the rectangle, HitTest returns Outside. If the hatched border handle of the rectangle was 
hit, returns MidCenter (inside). For any other hits, HitTest returns the location of the 
grapple that was hit. The enum TWhere defines the possible hit areas. 


Move 
void Move(int dx, int dy); 
Moves the rectangle relative to the values specified in dx and dy. 
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See also TUIHandle::MoveTo 


MoveTo 
void MoveTo(int x, int y); 
Moves the rectangle to the given x and y courdinaies 


See also TUIHandle::Move © 


Paint 
void Paint(TDC& dc) const; 
Paints the TUIHandle object onto the specified device context, dc. 


size 

void Size(int w, int h); 

Sets the size of the rectangle according to the measurements specified in w, ihe width, 
and. h, the height. 


TValidator class | : | validate.h 


A streamable class, TValidator defines an abstract data validation object. Although you 
will never actually create an instance of TValidator, it provides the abstract functions for 
the other data validation objects. 


The VALIDATE.CPP sample program on your distribution disk derives TValidateApp 
from TApplication in the following manner: 


class TValidateApp : public TApplication { 
public: 
TValidateApp() : TApplication("ValidateApp") {} 
void InitMainWindow() { 
MainWindow = new TTestWindow(0, "Validate Dialog Input"); 
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and displays the following message box if the user enters an invalid employee ID: 


Main application window 


CSO AQAA 
Validate Diela: 


After you 

choose Input!| 
Employee from 
the menu, the 
Employee Data 
Entry dialog box 
appears. 


lf an invalid 
employee ID is 
| entered, the 
see ee _ ValidateApp 
—— =< message box 
appears. 


Public constructor and destructor 


Constructor 
TValidator(); 
Constructs an abstract validator object and sets Options fields to 0. 


Destructor 
virtual ~TValidator(); a 
Destroys an abstract validator object. 


Public member functions 


Error 

virtual void Error(); 

Error is an abstract function called by Valid when it detects that the user has entered 
invalid information. By default, TValidator::Error does nothing, but derived classes can 
override Error to provide feedback to the user. 


HasOption 
bool HasOption(int option); 
Gets the Options bits. Returns true if a specified option is set. 


Seealso TValidator::Options, TValidatorOptions enum. 


IsValid 
virtual bool IsValid(const char far* str); 
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By default, TValidator::IsValid returns true. Derived validator types can override IsValid 
to validate data for a completed edit control. If an edit control has an associated | 
validator object, its Valid method calls the validator object's Valid method, which in turn 
calls IsValid to determine whether the contents of the edit control are valid. 


Seealso TValidator::Valid 


isValidInput 
virtual bool IsValidInput(char far* str, bool suppressFill); 
If an edit control has an associated validator object, it calls IsValidInput after processing 
each keyboard event. This gives validators such as filter validators an opportunity to 
_ catch errors before the user fills the entire item or screen. 


By default, IsValidInput returns true. Derived data validators can override IsValidInput 
to validate data as the user types it, returning true if str holds valid data and false 
otherwise. : 


str is the current input string. suppressFill determines whether the validator should 
automatically format the string before validating it. If suppressFill is true, validation 
takes place on the unmodified string str. If suppressFill is false, the validator should 
apply any filling or padding before validating data. Of the standard validator objects, 
only TPXPictureValidator checks suppressFill. 


IsValidInput can modify the contents of the input string; for example, it can force 
characters to uppercase or insert literal characters from a format picture. IsValidInput 
should not, however, delete invalid characters from the string. By returning false, 
IsValidInput indicates that the edit control should erase the incorrect characters. 


SetOption 
void SetOption(int option); 
Sets the bits for the Options data member. 


See also TValidator::Options, TValidatorOptions enum 


Transfer 

virtual uint Transfer(char far* str, void* buffer, TTransferDirection direction); 

Allows a validator to set and read the values of its associated edit control. This is 
primarily useful for validators that check non-string data, such as numeric values. For 
example, TRangeValidator uses Transfer to read and write values instead of transferring 
an entire string. | 


By default, edit controls with validators give the validator the first chance to respond to 
DataSize, GetData, and SetData by calling the validator's Transfer method. If Transfer 
returns anything other than 0, it indicates to the edit control that it has handled the 
appropriate transfer. The default action of TValidator::Transfer is to always return O. If 
you want the validator to transfer data, you must override its Transfer method. 


Transfer’s first two parameters are the associated edit control's text string and the 
tdGetData or tdSetData data record. Depending on the value of direction, Transfer can set 
str from buffer or read the data from str into buffer. The return value is always the 
number of bytes transferred. 


If direction is tdSizeData, Transfer doesn't change either str or buffer; it just returns the 
data size. If direction is tdSetData, Transfer reads the appropriate number of bytes from 
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buffer, converts them into the proper string form, and sets them into str, returning the 
number of bytes read. If direction is tdGetData, Transfer converts str into the appropriate 
data type and writes the value into buffer, returning the number of bytes written. 


Seealso ‘TTransferDirection enum 


UnsetOption 
void UnsetOption(int option); 
Unsets the bits specified in the Options data member. 


Seealso TValidator::Options, TValidatorOptions enum 


Valid 

bool Valid(const char far* str); 

Returns true if IsValid returns true. Otherwise, calls Error and returns false. A validator's 
Valid method is called by the Valid method of its associated edit control. 


Edit controls with associated validator objects call the validator's Valid method under 
two conditions. The first condition is when the edit control's of Validate option is set and 
the edit control calls Valid when it loses focus. The second condition is when the dialog 
box that contains the edit control calls Valid for all its controls, usually because the user 
requested to close the dialog box or to accept an entry screen. 


Protected data members 


Options 

uint16 Options; 7 
A bitmap member used to control options for various descendants of T Validator. By 
default, the [Validator constructor clears all the bits in Options. 


Seealso TVAlidatorOptions enum, TValidator::SetOption, TValidator:: UnsetOption 


Type definitions validate.h 


enum TValidatorOptions {voFill, voTransfer, voOnAppend, voReserved }; 
The TValidatorOptions enum constants represent bits in the bitmapped Options word in 
validator objects. 


Constant Meaning — ee oe S ne 

voFill Used by pcan calidatoret to indicate nenhert to 5 fill in hel piieratiegs as the user 
types. 

voTransfer The validator handles data transfer for the input line. Currently only used by range 
validators. 


voOnAppend Used by picture validators to determine how to interact with edit controls. 
voReserved The bits in this mask are reserved. 
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A nested class, TXValidator describes an exception that results from an invalid jalidatar 
object. That is, if a validator expression is not valid, this exception is thrown. 


Public constructor 


Constructor 

TXValidator(uint resid = IDS_VALIDATORSYNTAX); 

Constructs a TX Validator object, setting the resource ID to IDS_ VALIDATORSYNTAX 
string resource. 


TVbxControl class | vbxctl.h 


Derived from TControl, TVbxControl provides the interface for Visual Basic (VBX) 
controls. You can use this class to get or set the properties of VBX controls. Under certain 
conditions, you can also use additional methods for processing controls. 


You can manipulate the control's properties using either an index value or a name. 
Several overloaded GetProp functions are provided so that you can access different types 
of properties. Similarly, several overloaded SetProp functions let you set the properties 
of controls using either the name of the VBX control or the index value. Consult the 
documentation for your VBX controls to find the name that corresponds to the property 
you want to manipulate. 
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The VBXCTLX.CPP sample program on your distribution disks displays several VBX 
controls. 


Click Test to display 
the VBX controls Pictures Gauges 


SG . 
— eal Dialog Tester 


Test 


WeXContois fT 


Drag from he E OF Here... 


and drop here! 


Switches 


TVbxControl provides event-handling functions that process requests to compare, 
delete, draw, or measure VBX controls. If you want the TVbx control object to process 
additional VBX events, you can derive a class from TVbxControl and add a response 
table that has entries for the events you want processed. For information about creating 
response tables and handling VBX messages, see TVbxEventHandler. 


Public constructors and destructor 


Constructors 
TVbxControl(TWindow* parent, int id, const char far* voxName, const char far* vbxClass, const char far* title, 

int x, int y, int w, int h, long initLen = 0, void far* initData = 0, TModule* module = 0); 
Constructs a VBX control where parent points to the parent window, id is the control's 
ID, vbxName is the name of the file containing the VBX control, vbxClass is the VBX class 
name, title is the control's caption, x and y are the coordinates in the parent window 
where the controls are to be placed, w and h are the width and height of the control, and 
module is the library resource ID for the control. 


TVbxControl(TWindow* parent, int resourceld, TModule* module = 0); 
If a VBX control is part of a dialog resource, its ID can be used to construct a 
corresponding (or alias) ObjectWindows object. You can use this constructor if a VBX 


Chapter 2, ObjectWindows library reference 441 


 TVbxControl class — 


- Form 1 


control has saa beat defined in the applicatons: s resource file. resourceld is the 
resource ID of the VBX control in the resource file. i | 


Destructor 
~TVbxControl(); 


Destroys the TVbxControl object. 


Public member functions 


- Additem 


bool Additem(int index, const char far* item); 
Adds an item (item) to the list of VBX control items at the ccc index (index). Returns 
nonzero if successful. 


Drag 

bool Drag(int action); 

Controls the drag and drop state of the VBX control according to the value of action, 
which can be 0 (cancel a drag eee: 1 (begin dragging a control), or 2 (end 
dragging a control). 


GetEventindex 

int GetEventIndex(const char far* name): | 

Returns the index of the event associated with the name of the event passed in name. 
Returns —1 if an error occurs. 


~ GetEventName 


const char far* GetEventName(int eventindex); 
Returns a string containing the name of an event associated with the ieee: event index 
number (eventindex). Returns 0 if an error occurs. 


GetHCTL 
HCTL GetHCTL(); 7 
Returns a handle to a VBX control associated with this TVbxControl object. 


GetNumEvents 


~ int GetNumEvents(); 


Returns the total number of events associated with the VBX control. 


GetNumProps 
int GetNumProps(); 
Returns the total number of properties associated with the VBX control. 


GetProp 


bool GetProp(int propindex, int value, int arraylndex = —1); 

Gets an integer property value. An overloaded function, GetProp gets a VBX control 
property using an index value. propIndex is the index value of the property whose value 
you want to get. value is a reference to the variable that will receive the property values. 
arrayIndex, an optional argument, specifies the position of the value in an array property 
if the property is an array type. If the property isn't an array type, arrayIndex defaults to | 
-1. See the third-party reference guide for your VBX controls to determine a property's 
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Form 3 


Form 4 


Form 5 


Form 6 


Form 7 


Form 8 


Form 9 


Form 10 


Form 11 


Form 12 


Form 13 


Form 14 
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data type. GetProp returns nonzero if successful. To get the property by specifying the 
property index, use one of the following six GetProp functions. 


bool GetProp(int propindex, long& value, int arraylndex = —1); 
Gets a long property value. 


bool GetProp(int propindex, ENUM& value, int arrayindex=—1); 
Gets an enumerated property value. For example, a list of options associated with a font 
style might be defined as an enumerated type. 


bool GetProp(int propindex, HPIC& value, int arraylndex=—1); 
Gets a picture (value). HPIC is a handle to the picture. 


bool GetProp(int propindex, float& value, int arraylndex = =—1): 
Gets a floating-point property value. 


bool GetProp(int propindex, string& value, int arraylndex = —1); 
Gets a string property value. 


bool GetProp(int propIndex, COLORREF value, int arrayIndex = —1); 
Gets a color property value. 


bool GetProp(const char far* name, int& value, int arraylndex = —1); 

Returns an integer data value. An overloaded function, GetProp gets a VBX control 
property. propIndex is the index value of the property whose value you want to get. value 
is a reference to the variable that will receive the property value. arrayIndex, an optional 
argument, specifies the position of the value in an array property if the property is an 
array type. If the property isn't an array type, arrayIndex defaults to —1. GetProp returns 
nonzero if successful. To get the property by specifying the name of the property, use 
one of the following five GetProp functions. 


bool GetProp(const char far* name, long& value, int arraylndex = —1); 
Gets a long property value. 


bool GetProp(const char far* name, float& value, int arrayindex = —1); 
Gets a floating-point property value. 


bool GetProp(const char far* name, ENUM& value, int arrayindex=—1); 
Gets an enumerated property value. 


bool Getprop(const char far* name, HPIC& value, int arraylndex=—1); 
Gets a picture (value) property value. HPIC is a handle to the picture. 


bool GetProp(const char far* name, string& value, int arrayindex = —1); 
Gets a string property value. 


bool GetProp(const char far* name, COLORREF value, int arraylndex = —1); 
Gets a string color property value. 


Seealso TVbxControl::SetProp 
GetPropindex 
int GetPropIndex(const char far* name); 


Gets the integer index value for the property name passed in name. Returns —1 if an error 
occurs. This usually indicates that the property name passed in name couldn't be located. 
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Form 1 


Form 2 


Form 1 


Form 2 


-GetPropName | 


const char far* GetPropName(int propIndex): 
Gets the name for the property index passed in index. Returns 0 if an error occurs. 


GetPropType 
int GetPropType(int propIndex); 


int GetPropType(char far* name); 


_ Form 1 gets the type for the property specified by index. Form 2 sets the property string 


type specified by name. Returns 0 if an error occurs. The following table lists the names 
of the property types and their corresponding C++ data types. 


PTYPE_CSTRING HSZ 
PTYPE_SHORT short 
PTYPE_LONG int32 
PTYPE_BOOL bool 
PTYPE_COLOR uint32 or COLORREF 
PTYPE_ENUM uint8 or ENUM 
PTYPE_REAL float 
PTYPE_XPOS int32 (Twips) 
PTYPE_XSIZE int32(Twips) 
PTYPE_YPOS int32 (Twips) 
PTYPE_YSIZE  int32 (Twips) 
PTYPE_PICTURE HPIC 
PTYPE_BSTRING HLSTR 
IsArrayProp 


bool IsArrayProp(int propindex); 


bool IsArrayProp(char far* name); 
Returns true if the property specified by index (Form 1) or name ebta 2) is an array 


property. 


Method 

bool Method(int method, long far* args); 

Used for invoking customized methods, Method returns true if a VBX control can 
respond to the specified method (method). 


Move 

bool Move(long x, long y, long w, long h); 

Moves a VBX control to the coordinates specified in x and y, which designate the upper 
left corner screen coordinates. Resizes the VBX control to w twips wide by h twips high. 
Returns nonzero if successful. 


Refresh 
bool Refresh(); | 
Repaints the control's display area. 
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Removeltem 

bool Removeltem(int index); 

Removes an item (specified by index). The item could be removed from a list box, a 
combo box, or a database, for example. 


SetProp | 

bool SetProp(int propindex, int value, int arraylndex = —1): 

Sets the property to an integer value. An overloaded function, SetProp sets a VBX control 
property. propIndex is the index number of the property whose value you want to set. 
value specifies the new value for the property. arrayIndex specifies the position of the 
value in an array property if the property is an array type. If the property isn't an array 
type, arrayIndex defaults to —1. To set the property by passing the property's index value, 
use one of the following six SetProp functions. 


bool SetProp(int propindex, long value, int arrayIndex = —1); 
Sets the property to a long value. 


bool SetProp(int propIndex, ENUM value, int arraylndex=—1): 
Sets the property to an enumerated value. 


bool SetProp(int propindex, HPIC value, int arraylndex=—1); 
Sets a picture to an HPIC, or picture, value. 


bool SetProp(int propindex, float value, int arrayindex = —1); 
Sets the property to a floating-point value. 


bool SetProp(int propindex, const string& value, int arraylndex = —1); 
Sets the property to a string value. 


bool SetProp(int propindex, const char far* value, int arrayindex = —1); 
Sets the property to a character string value. 


bool SetProp(int propIndex, COLORREF value, int arraylndex = —1); 
Sets the property to a color value. 


bool SetProp(const char far* name, int value, int arrayindex = —1); 

Sets the property to an integer value. An overloaded function, SetProp sets a VBX control 
property. arrayIndex specifies the position of the value in an array property if the 
property is an array type. If the property isn't an array type, arrayIndex defaults to -1. To 
set the property by using the property's name, use one of the following six SetProp 
functions. 


bool SetProp(const char far* name, long value, int arrayIndex = —1); 
Sets the property to a Jong value. 


bool SetProp(const char far* name, ENUM value, int arraylindex=—1); 
Sets the property to an enumerated value. 


bool SetProp(const char far* name, HPIC value, int arraylndex = —1); 
Sets the picture property to an HPIC, or picture, value. 


bool SetProp(const char far* name, float value, int arraylndex = —1); 
Sets the property to a floating-point value. 


bool SetProp(const char far* name, const string& value, int arraylndex = —1); 
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Sets the property to a string value. 


bool SetProp(const char far* name, const char far* value, int arrayIndex = —1); 
Sets the property to a character string value. 


bool SetProp(const char far* name, COLORREF value, int arrayindex = -1); 
Sets the property to a color string value. 


Seealso T'VbxControl::GetProp 


SetUpWindow 

void SetupWindow(); 

A VBX control has an HWND Diels a VBX handle. Usually, the VBX control handle is 
created first. However, if the window has already been created, you can use this 
function to extract the VBX control handle. 


Protected member functions 


GetClassName 
char far* GetClassName(); 


Gets the name of the VBX window class. 


GetVBXProperty 

bool GetVBXProperty(int propIndex, void far* value, int arrayIndex = —1); 

Returns nonzero if the specified property exists. propIndex specifies the index value of 
the integer property whose value you want to get. value points to the variable where the 
value will be stored. 


PerformCreate 

void PerformCreate(int menuOrld); 

Creates a new control window and associates the VBX control with the window. 
Establishes the control ID, the VBX control name and class, and the window caption. 
Sets Atir.style to the window style of the control, Attr.X and Attr.Y to the upper left 
screen coordinates of the control, and Attr.W and Aitr.H to the width and height of the 
control. 


SetVBXProperty 

bool SetVBXProperty(int propindex, int32 value, int arraylndex=—1); | 

Returns nonzero if the specified property value is set, or 0 if unsuccessful. propindex is 
the index number of the property whose value you want to set. value is the value to be 
stored. An optional argument, arrayIndex, which is —1 by default, specifies the index 
value in an array of values of the property to be set. 


Response table entries 


The TVbxControl class has no response table entries. 
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Derived from TEventHandler, TVbxEventHandler handles events from VBX controls. 
Although you will never need to modify this class, TVbxEventHandler needs to be mixed 
in with your window class so that it can receive events from VBX controls. For example, 


class TMyWindow:public TWindow, public TVbxEventHandler 
{ 


// Include class definition here. 


} 


The following diagram illustrates the flow of information between VBX controls, parent 
windows, and response tables. 
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When a VBX control fires an event Gnd an event message), the pisces sequence i 
events occurs: 


1 The VBX Control sends a WM_VBXFIREEVENT message to TMyWindow. 


2 TMyWindow's TVbxEventHandler finds a WM _VBXFIREEVENT message in its 
response table and calls EvVbxDispatch. 


3 Ifachild window is present, EvuVbxDispatch dispatches the event to the child. 


4 If there is an event-handling function in the child window's response table, the child 
window handles the event. 


5 If there is no child window, or the child window doesn't handle the event, 
EvVbxDispatch dispatches the event to TMyWindow’s response table. 
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In other odaeis when a VBX control ae a WM. VBXFIREEVENT message, the parent 

window's TVbxEventHandler catches this message first, converts it into a form 
understood by a window's response table, and attempts to send the converted message — 
to the child window. If there is no child window or if the child window doesn't handle 
the message, TVbxEventHandler sends the converted message to the parent window. 
When the parent window receives the message, it calls the handler function that 
corresponds to the message. 


Two response table macros, EV_VBXEVENTNAME and EV _VBXEVEN" TINDEX, map 
VBX events to handler functions. Of the two macros, EV_VBKEVENTNAME is more 

commonly used. EV_VBXEVENTINDEX is intended for use with code generators, 
which can determine the event index values for a VBX control. Both macros call an event 
handler function and point to the VBXEVENT structure. A typical 
EV_VBXEVENTNAME response table entry might be 


EV_VBXEVENTNAME (IDC_ BUTTON1, _"MouseMove", EvMouseMove) ; 


where IDC_BUTTON]1 is the sete ID, "EvMouseMove' is the acent name, and 
EvMouseMove is the handler function. 


The lparam of aWM_VBX FIREEVENT message points to a VBXEVENT structure, 
which holds information about the event and the control that generated the event. The 
VBXEVENT structure contains the following members: 


typedef struct VBXEVENT { 
HCTL Control; 
HWND Window; 


Ine ID; 
int Event Index; 
LPCSTR EventName; 
int NumParams; 
LPVOID ParamList; 
} VBXEVENT; 
where 


© Control is a handle to the VBX control sending the message. 
© Window is the handle of the VBX control window. 
e [Dis the ID of the VBX control. 
e EventIndex is the event index. 
e EventName is the name of the event. — 
¢ NumParams holds the number of event arguments. 


¢ ParamList is a pointer to a list of pointers to the event's arguments. The ParamList data 
member provides access to the actual arguments of the event. | 


To handle VBX events, your program uses an event-handling function. In the following 
example, EvMouseMove is the name of the handler function, which passes a pointer to 
the VBXEVENT event structure. VBX_EVENTARGNUM is the macro that takes event, 
type, and an index number as its parameters. event references the VBXEVENT structure, 
short is the event argument type, and 0 and 1 are the index numbers of the argument. 


\ 
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The argument types and indexes can be found in the documentation for the VBX 
control. 


vold EvMouseMove (VBXEVENT FAR* event) 

{ 
short X = VBX_EVENTARGNUM(event, short, 0); 
short Y = VBX_EVENTARGNUM(event, short, 1); 


} 


Because VBX controls were originally designed to be used with Visual Basic, their event 
arguments are documented in terms of Basic data types. The following table lists the 
Basic types, their C++ equivalents, and macros. 


Basic Le CH ee Macro c ee 8 Pe. 
Boolean short = = VBX_EVENTARGNUM(event, short, index) — 
Control HCTL VBX_EVENTARGNUM(C(event, HCTL, index) 
Double double VBX_EVENTARGNUM( (event, double, index) 
Enum short VBX_EVENTARGNUM(event, short, index) 
Integer short VBX_EVENTARGNUM (event, short, index) 
Long long VBX_EVENTARGNUM event, long, index) 
Single float VBX_EVENTARGNUMCevent, float, index) 
String HLSTR VBX_EVENTARGSTR (event, index) 


The following table lists the standard VBX events and corresponding arguments that the 
Borland C++ VBX emulation library supports. 


Click None 

DblClick None 

DragDrop Source as Control, X as Integer, Y as Integer 

DragOver Source as Control, X as Integer, Y as Integer, State as Integer 
GotFocus None 

KeyDown _ Key as Integer, Shift as Integer 

KeyPress Key as Integer, Shift as Integer 

KeyUp Key as Integer, Shift as Integer 

LostFocus None | 


MouseDown X as Integer, Y as Integer 
MouseMove X as Integer, Y as Integer, Shift as Integer, Button as Integer 
MouseUp X as Integer, Y as Integer, Shift as Integer, Button as Integer 


For the DragOver event, the state argument can be one of the following values: 
_ © 0, where the source control is being dragged within a target's range. 
° 1,where the source control is being dragged out of a target's range. 


e 2, where the source control is being moved from one position in the target to another. 
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For both the DragOver and DragDrop events, the Control a oanent type should be | 
translated to HCTL (a handle to the VBX ee! for C++. The X and Y values are in 
pixels, not twips. : 


If a standard VBX event has a Shift key argument, the argument has these bit values: 


Shift Ox1 
Ctrl Ox2 . 
Alt 0x4 (Used in connection with a Menu selection) 


If a standard VBX event has a Button key argument, the argument has these bit values: 


Left Ox1 
Right Ox2 
Middle Ox4 


The following example shows how you might use these Shift key arguments. For 
example, if you want the VBX control to perform some action when the mouse is moved 
and the Shift key is pressed, you could write a function such as 


void EvMouseMove (VBXEVENT FAR* event) 

{ 

short X = VBX_EVENTARGNUM(event, short, 0); 
short Y = VBX_EVENTARGNUM(event, short, 1); 
short Shift = VBX_EVENTARGNUM(event, short, 2); 

_ ghort Button = VBX_EVENTARGNUM(event, short, 3); 
if (shift & 0x2) 

| MessageBox ("The control key is pressed."); 

} 

Borland C++ uses pixels to express the X and Y coordinate arguments of standard VBX 

events. This differs from Visual Basic, which expresses coordinates in twips (1/20th of a 

point or 1/1440 of an inch). Custom events are usually expressed in terms of twips. You 

can use these functions to convert between pixels and twips. 


VBXPix2TwpX Converts an X argument from pixels to twips. 


VBXPix2TwpY Converts a Y argument from pixels to twips 
VBXTwp2PixX Converts an X argument from twips to pixels 
VBXTwp2PixY Converts a Y argument from twips to pixels 


Protected member functions 


EvVbxDispatch 
LRESULT EvVbxDispatch(WPARAM wp, LPARAM Ib): 
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After TVbxEventHandler receives a WM_VBXFIREEVENT message from the parent 
window, it calls EvVbxDispatch, which sends the message to the correct event-handling 
function and passes a pointer to the VBXEVENT structure. 


EvVbxinitForm 
LRESULT EvVbxInitForm(WPARAM wp, LPARAM Ip); 


Response table entries 


Response table entry Member function 
EV_MESSAGE(WM_VBXFIREEVENT, EvVbxDispatch) EvVbxDispatch 
EV_MESSAGE(WM_VBXINITFORM, Ev VbxinitForm) EvVbxInitForm 

TView class docview.h 


Derived virtually from both TEventHandler and TStreamableBase, TView is the interface 
presented to a document so it can access its client views. Views then call the document 
functions to request input and output streams. Views own the streams and are 
responsible for attaching and deleting them. 


Instead of creating an instance of TView, you create a derived class that can implement 
TView’s virtual functions. The derived class must have a way of knowing the associated 
window (provided by GetWindow) and of describing the view (provided by 

Get ViewName). The view must also be able to display the document title in its window 
(SetDocTitle). 


TView uses several event handler functions to query views, commit, and close views. 
For example, if a view is associated with a window that can gain focus, then it should 
handle the vnIsWindow notification message. 


View classes can take various forms. For example, a view class can be a window 
(through inheritance), can contain a window (an embedded object), can reference a 
window, or can be contained within a window object. A view class might not even have 
a window, as in the case of a voice mail or a format converter. Some remote views (for 
example, those displayed by DDE servers) might not have local windows. 


Other viewer classes derived from TView include TEditView, TList View, and 
TWindowView. These classes display different types of data: TEditView displays 
unformatted text files, TList View displays text information in a list box, and 
TWindowView is a basic viewer from which you can derive other types of viewers such 
as hex file viewers. 


For OLE-enabled applications, use TOleView, which supports views for embedded 
objects and compound documents. 


See also 
TOleView class 
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Public data members _ 


enum 

enum Pannier 0, ViewClass, ViewName, NextProperty,}: 

These property values, defined for TView, are available in classes derived from TView. 
PrevProperty and NextProperty are delimiters for every document's property list. 


Tag 

void far* Tag; , | 

Tag holds a pointer to the application defined data. Typically, you can use Tag to install 
a pointer to your own application's associated data structure. TView zeros Tag during 
construction and doesn't access it again. 


Public constructor and destructor 


Constructor 
TView(TDocument& doc); 
Constructs a TView object of the document associated with the view. Sets Viewld to 
_ NextViewld. Calls TDocument::AttachView to attach the view to the associated document. 


Destructor 

virtual ~TView(); 

Frees a TView object and calls DetachView to detach the view from the associated 
document. 


Public member functions 


FindProperty 
virtual int FindProperty(const char fart name); 

& indProperty gets the property index, given the property name (name). Returns 0 if the 
name isn't found. 


See also pfxxxx property access constants 


GetDocument 
TDocument& GetDocument(); 
Returns a reference to the view's document. 


GetNextViewld 
static unsigned GetNextViewld{}; 
Returns the next view ID to be assigned. 


GetProperty 

virtual int GetProperty(int index, void far* dest, int textlen=0); 

Returns the total number of properties where index is the meee index, dest contains 
the property data, and textlen is the size of the property array. If textlen is 0, property 
data is returned as binary data; otherwise, property data is returned as text data. 


See also pfxxxx property access constants, TView::SetProperty 
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GetViewld 
unsigned GetViewld(); 
Returns the unique ID for this view. 


GetViewMenu 

TMenuDescr* GetViewMenu(); 

Returns the menu descriptor for this view. This can be any existing TMenuDescr object. 
If no descriptor exists, ViewMenu is 0. 


GetViewName 

virtual const char far* GetViewName()=0; 

Pure virtual function that returns 0. Override this function in yeu derived class to 
return the name of the class. 


Seealso TEditView::StaticName, TEditView::GetView Name 


GetWindow 
virtual TWindow* GetWindow() 
GetWindow returns the TWindow instance associated with the view or 0 if no view exists. 


Seealso TeditView::GetWindow 


IsOK 
bool IsOK(); 
Returns nonzero if the view is successfully constructed. 


Seealso TView::NotOK 


PropertyCount 
virtual int PropertyCount(); 
Gets the total number of properties for the TDocument object. Returns NextProperty -1. 


See also pfxxxx property access constants 
PropertyFlags 
virtual int PropertyFlags(int index); 


Returns the attributes of a specified property given the index (index) of the property 
whose attributes you want to retrieve. 


Seealso pfxxxx property access constants, TView::FindProperty, 
TView::PropertyName 


PropertyName 
virtual const char* PropertyNamefint index); 
Returns the text name of the property given the index value. 


Seealso pfxxxx property access constants, TView::FindProperty 


SetDocTitle 
virtual bool SetDocTitle(const char far* docname, int index) 
Stores the document title. 


See also TWindow::SetDocTitle 
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SetProperty 

virtual bool SetProperty(int index, const void far* src); 

Sets the value of the property, given the index of the property, and src, the data type 
(either binary or text) to which the property must be set. 


See also pfxxxx property access constants, TView::GetProperty 


SetViewMenu 

void SetViewMenu(TMenuDescr* menu); | 

Sets the menu descriptor for this view. This can be any existing TMenuDescr object. If no 
descriptor exists, ViewMenu is 0. 


Seealso TView::GetViewMenu 


Protected data member 


Doc 
TDocument* Doc; 
Holds the current document. 


Protected member functions 


NotOK 
void NotOK(); 
Sets the view to an invalid state, thus causing IsOK to return 0. 


Seealso TView::IsOK 


enum TWidthHeigh {lmWidth = ImCenter + 1, ImHeight}; 
Used by the TLayoutConstraint struct, TWidthHeight enumerates the values that control 
the width (ImWidth) and height (ImHeight) of the window. 


Seealso TLayoutConstraint struct 


TWindow class | ~ window.h 


TWindow, derived from TEventHandler and TStreamableBase, provides window-specific 
behavior and encapsulates many functions that control window behavior and specify 
window creation and registration attributes. 


TWindow is a generic window that can be resized and moved. You can construct an 
instance of TWindow, though normally you'll use TWindow as a base for your specialized 
window classes. In general, to associate and disassociate a TWindow object with a 
window element, you need to follow these steps: 


1 Construct an instance of a TWindow. 
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2 Call Create or Execute, which creates the interface element (HWND) and then calls 
SetupWindow, which calls the base SetupWindow for normal processing, which in turn 
involves 


e Creating the HWindow and any child HWindows. 


¢ Calling TransferData to setup the transfer of data between the parent and child 
windows. 


3 To destroy the interface element, choose one of the following actions, depending on 
your application: 


e Call Destroy to destroy the interface element unconditionally. 


¢ Call CloseWindow, which calls CanClose to test whether it's OK to destroy the 
interface element. 


4 There are two ways to destroy the interface object: 
° If the object has been new'd, use delete. 


e If the object hasn't been new'd, the compiler automatically destructs the object. 


The ObjectWindows destroy process consists of two parts: (1) call Destroy to destroy the 
interface element and (2) then delete the C++ object. However, it is perfectly valid to call 
Destroy on the interface element without deleting the C++ object and then to call Create 
at a later time to re-create the window. Because it is also valid to construct a C++ 
window object on the stack or as an aggregated member, the Destroy function can't 
assume it should delete the C++ object. 


The user-generated WM_CLOSE event handler, EvClose, also causes a C++ object to be 
deleted by passing the "this" pointer to the application. The C++ object is deleted 
automatically because the EvClose event frequently occurs in response to a user action, 
and this is the most convenient place for the deletion to take place. Later, when it's safe 
to do so, the application then deletes the window pointer. Because the stack often 
contains selectors that refer to the addresses of objects that may become invalid during 
the delete process, it's not safe to delete the "this" pointer while events are still being 
processed. If the addresses become invalid, they could cause trouble when they are 
reloaded from the stack. 


TWindow is the base class for all window classes, including TFrameWindow, TControl, 
TDialog, and TMDIChild. The ObjectWindows hierarchy diagram shows the many 
classes that are derived from TWindow. 


Public data members 


Attr 

TWindowAttr Attr; 

Holds a TWindowAttr structure, which contains the window's creation attributes. These 
attributes, which include the window's style, extended style, position, size, menu ID, 
child window ID, and menu eee table ID, are passed to the function that creates 
the window. 


Seealso TWindow::TWindow, idea TWindowAttr struct 
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DefaultProc 

WNDPROC DefaultProc; 

Holds the address of the default window procedure. DefWindowProc calls DefaultProc t to” 
process Windows messages that are not handled by the window. 


See also TWindow::DefWindowProc 
HWindow 
HWND HWindow; 


Holds the handle to the associated MS-Windows indow: which you'll need to access if 
you make calls directly to Windows API functions. 


Parent 

TWindow* Parent; | 

Points to the interface object that serves as the parent window for this interface object. 
Scroller 

TScroller* Scroller; 


Points to the scroller object that supports either the horizontal or vertical scrolling for 
this window. 


Status 
TStatus Status; 
Status is used to signal an error in the initialization of an interface object. Setting Status to. 
a nonzero value causes a TXIncompatibility exception to be thrown. Classes derived from 
_ TWindow do not attempt to associate an interface element with an object whose previous 
initialization has failed. Status is included only to provide paekware compatibility with 
previous versions of ObjectWindows. 


Title 

char far* Title; 

Title points to the window's caption. When there is a valid HWindow, Title will yield the 
same information as ::GetWindowText if you use TWindow::SetCaption to set it. 


Seealso TDialog::SetCaption, TDialog::SetupWindow, 
TWindow::GetWindowTextTitle, TWindow::SetCaption 


Public constructors and destructor 


Constructors 

Form 1 = TWindow(HWND hWnd, TModule* module = 0); 
Constructs a TWindow that is used as an alias for a non-ObjectWindows window, and 
sets wfAlias. Because the HWND is already available, this constructor, unlike the other 
TWindow constructor, performs the "thunking" and extraction of HWND information 
instead of waiting until the function Create creates the interface element. 


Both forms: The following paragraphs describe procedures common to both 
constructors. module specifies the application or DLL that owns the TWindow instance. 
ObjectWindows needs the correct value of module to find needed resources. If module 
is 0, TWindow sets its module according to the following rules: 
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e Ifthe window has a parent, the parent's module is used. 


e Ifthe TWindow constructor is invoked from an application, the module is set to the 
application. 


e Ifthe TWindow constructor is invoked from a DLL that is dynamically linked with the 
ObjectWindows DLL and the currently running application is linked the same way, 
the module is set to the currently running application. 


e Ifthe TWindow constructor is invoked from a DLL that is statically linked with the 
ObjectWindows library or the invoking DLL is dynamically linked with 
ObjectWindows DLL but the currently running application is not, no default is used 
for setting the module. Instead, a TXInvalidModule exception is thrown and the object 
is not created. 


TWindow(TWindow* parent, const char far* title = 0, TModule* module = 0); 

Adds this to the child list of parent if nonzero, and calls EnableAutoCreate so that this will 
be created displayed along with parent. Also sets the title of the window initializes the 
window's creation attributes. 


See the previous constructor for a description of the procedures common to both 
constructors. 


Destructor 

virtual ~TWindow(); 

Destroys a still-associated interface element by calling Destroy. Deletes the window 
objects in the child list, then removes this from the parent window's child list. Deletes 
the Scroller if it is nonzero. Frees the cursor, if any exists, and the object instance (thunk). 


Seealso TWindowFlag enum, TWindow::EnableAutoCreate 


Public member functions 


AdjustWindowRect 

static void AdjustWindowRect(TRect& rect, uint32 style, boo! menu); 

Adjust WindowRect calculates the size of the window rectangle according to the indicated 
client-rectangle size. rect refers to the structure that contains the client rectangle's 
coordinates. style specifies the style of the window. menu is true if the window has a 
menu. 


AdjustWindowRectEx 

static void AdjustWindowRectEx(TRect& rect, uint32 style, bool menu, uint32 exStyle); 
AdjustWindowRectEx calculates the size of a window rectangle that has an extended 
style. TRect refers to the structure that contains the client rectangle's coordinates. style 
specifies the window styles of the window to be adjusted, and menu returns true if the 
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window has a menu. ex tyle indicates the extended styles to be used for the window. 
_ Extended styles include the following styles: 


WS_EX_ACCEPTFILES The window can make use of drag and drop files. 


WS_EX_DLGMODALFRAME ___ The window has a double border that can be created with a title bar if 
the WS_CAPTION style flag is specified. 


WS_EX_NOPARENTNOTIFY The child window created from this style does not send parent notify 
| messages to the parent window when the child is created or 


| destroyed. | 
WS_EX_TOPMOST A window having this style is placed above windows that aren't 
topmost and remains above the non-topmost windows even when it's 
deactivated. 


WS_EX_TRANSPARENT A window having this style is transparent, that is, any windows 
- beneath this window are not concealed by this window. | 


Seealso TWindowAttr struct 


BringWindowToTop 

void BringWindowToTop(); — 

BringWindowToTop brings a pop-up or child window to the top of the stack of 
overlapping windows and activates it. 


CanClose 

virtual bool CanClose(); 

Use this function to determine if it's okay to close a ado Returns true if the 
associated interface element can be closed. Calls the CanClose member function of each 
of its child windows. Returns false if any of the CanClose calls returns false. 


In your application's main window, you can override TWindow’s CanClose and call 
TWindow::MessageBox to display a YESNOCANCEL message prompting the user to 


YES—Save the data, or 
NO—Don't save the data, but close the window, or 
CANCEL—Cancel the close operation and return to the edit window. 


The following example shows how to write a CanClose function that displays a message 
box asking if the user wants to save a drawing that has changed. To save time, CanClose 
uses the IsDirty flag to see if the drawing has changed. If so, CanClose queries the user 
before closing the window. 


bool TMyWindow: :CanClose() 
{ 
if (IsDirty) 
Switch (MessageBox("Do you want to save?", "Drawing has changed.", 
MB_YESNOCANCEL | MB_ICONQUESTION)) { 
case IDCANCEL : 

// Choosing Cancel means to abort the close — return ao 
return false; 


case IDYES: | 
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// Choosing Yes means to save the drawing. 
CmFileSave(); 


} 


return true; 


} 


CheckDigButton 

void CheckDigButton(int buttonld, uint check); 

Places a checkmark in (or removes a checkmark from) the button specified in buttonId. If 
check is nonzero, the checkmark is placed next to the button; if 0, the checkmark is 
removed. For buttons having three states, check can be 0 (clear), 1 (checked), or 2 (gray). 


CheckRadioButton 

void CheckRadioButton(int firstButtonld, int lastButtonld, int checkButtonld); 

Checks the radio button specified by checkButtonId and removes the checkmark from the 
other radio buttons in the group. firstButtonId and lastButtonId specify the first and last 
buttons, respectively, in the group. 


ChildBroadcastMessage 
void ChildBroadcastMessage(uint msg, WPARAM wParam, LPARAM |Param); 
Sends the specified message to all immediate children using SendMessage. 


See also TWindow::SendMessage 


ChildWindowFromPoint 

HWND ChildWindowFromPoint(const TPoint&) const; 

Determines which of the child windows contains the point specified in TPoint. Returns a 
handle to the window that contains the point, or 0 if the point lies outside the parent 
window. 


Seealso TWindow::WindowFromPoint 


ChildWithid 

TWindow* ChildWithld(int id) const; 

Returns a pointer to the window in the child window list that has the supplied ID. 
Returns 0 if no child window has the indicated id. 


ClearFlag 

void ClearFlag(TWindowFlag mask); 

Clears the specified TWindow wfXxxx constant flags (for example wfAlias, wfTransfer, 
and so on) in the Flags member. 


Seealso T’WindowFlag enum 


ClientToScreen 

void ClientToScreen(TPoint& point) const; 

Converts the client coordinates specified in TPoint to screen coordinates for the new 
window. 


CloseWindow 

virtual void CloseWindow(int retval = 0); 

Determines if it's okay to close a window before actually closing the window. If this is 
the main window of the application, calls GetApplication->CanClose. Otherwise, calls 
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Form 1 


Form 2 


this->CanClose to determine whether the window can be closed. After determining that 


it is okay to close the window, CloseWindow calls Destroy to destroy the HWND. 


Seealso TApplication::CanClose, TWindow::CanClose 
CmExit 


void CmExit(); 


CmExit is called in response to the selection of a menu item that has an ID of CM_EXIT. 
If this is the main window, CmExit calls CloseWindow. 


Create 

virtual bool Create(); 

Creates the windows interface element to be associated with this ObjectWindows 
interface element. 


CreateCaret | 
void CreateCaret(HBITMAP hBitmap); 
Creates a new caret for the system. HBITMAP specifies the bitmapped caret ee 


void CreateCaret(bool isGray, int width, int height); 
Create a new caret for the system with the specified shape, bitmap shade, width, and 
height. If width or height is 0, the corresponding system-defined border size is used. 


CreateChildren 

bool CreateChildren(); 

Creates the child windows in the child list whose auto-create flags (with wfAutoCreate 
mask) are set. 


See also TWindow: ‘EnableAutoCreate, TWindow::DisableAutoCreate, pe ING OMIETAg 
enum 


| DefaultProcessing 


LRESULT DefaultProcessing(); 

DefaultProcessing serves as a general-purpose default processing function that handles a 
variety of messages. After being created and before calling DefaultProcessing, however, a 
window completes this sequence of events: | 


e If the window is already created, SubclassWindow is used to install StdWndProc in 
place of the window's current ut procedure. The previous window procedure is saved 
in DefaultProc. 


e If the window hasn't been created, InitWndProc is set up as the window proc in the 
class. Then, when the window first receives a message, InitWndProc calls GetThunk to 
get the window's instance thunk (created by the constructor by calling 
CreateInstanceThunk). InitWndProc then switches the message-receiving capability 
from the window's procedure to StdWndProc. 


After this point, StdWndProc responds to incoming messages by calling the window's 
virtual WindowProc to process the messages. ObjectWindows uses the special registered 
message ::GetWindowPirMsgld to get the this pointer of an HWND. StdWndProc 
responds to this message by returning the this pointer obtained from the thunk. 


If the incoming message is not a command or command enable message, WindowProc 
immediately searches the window's response table for a matching entry. If the incoming 
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message is a command or command enable message, WindowProc calls EvCommand or 
EvCommandEnable. EvCommand and EvCommandEnable begin searching for a matching 
entry in the focus window's response table. If an entry is found, the corresponding 
function is dispatched; otherwise ObjectWindows calls DefaultProcessing to finish the 
recursive walk back up the parent chain, searching for a match until the receiving 
window (the window that initially received the message) is reached. At this point, one 
of the following actions occurs: 


If there is still no match and this is the MainWindow of the application, the window 
searches the application's response table. 


It there are no matches and this is a command, DefWindowProc is called. 
If this is a CommandEnable message, no further action is taken. 


If this is not a command, and if a response table entry exists for the window, 
WindowProc dispatches the corresponding EvXxxx function to handle the message. 


If this is the application's MainWindow, and the message is designed for the 
application, the message is forwarded to the application. 


For any other cases, the window calls DefWindowProc. 
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The following diagram illustrates this sequence of message-processing events: 
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Seealso TWindow::DefWindowProc 


DefWindowProc 

virtual LRESULT DefWindowProc(uint msg, WPARAM wParam, LPARAM Param) 

Performs default Windows processing and passes the incoming Windows message. You 
usually don't need to call this function directly. Classes such as TMDIFrame and 
TMDIChild’s DefWindowProc override this function to perform specialized default 
processing. 


Seealso TWindow::DefaultProc, TWindow::WindowProc, 
TMDIFrame::DefWindowProc 


Destroy 

virtual void Destroy(int retVal = 0); 

First, Destroy calls EnableAutoCreate for each window in the child list to ensure that 
windows in the child list will be re-created if this is re-created. Then, it destroys the 
associated interface element. 


If a derived window class expects to be destructed directly, it should call Destroy as the 
first step in its destruction so that any virtual functions and event handlers can be called 
during the destroy sequence. 


Seealso TWindow::EnableAutoCreate 


DestroyCaret 

static void DestroyCaret(); 

DestroyCaret first checks the ownership of the caret. If a window in the current task owns 
the caret, DestroyCaret destroys the caret and removes it from the screen. 


Seealso TWindow::CreateCaret 


DisableAutoCreate 

void DisableAutoCreate(); 

Disables the feature that allows an associated child window interface element to be 
created and displayed along with its parent window. Call DisableAutoCreate for pop-up 
windows and controls if you want to create and display them at a time later than their 
parent windows. 


See also TWindow::EnableAutoCreate 


DisableTransfer 

void DisableTransfer(); 

Disables (for the interface object) the transfer mechanism, which allows state data to be 
transferred to and from a bone buffer. 


Seealso TWindowFlag enum 
Dispatch 
virtual LRESULT Dispatch(TEventinfo& info, WPARAM wp, LPARAM Ip = 0); 


Cracks and dispatches a TWindow message. The info parameter is the event-handling 
function. The wp and Ip parameters are the message parameters the dispatcher cracks. 


DragAcceptFiles 
void DragAcceptFiles(bool accept); 
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DrawMenuBar 

void DrawMenuBar(); 

DrawMenuBar redraws the menu bar. This function should be called to redraw the 
menu if the menu is changed after the window is created. 


EnableAutoCreate- 

void EnableAutoCreate(); 

Ensures that an associated child-window interface element is created and displayed 
along with its parent window. By default, this feature is enabled for windows and 
controls, but disabled for dialog boxes. 


See also TWindow::DisableAutoCreate 


- EnableScrollBar 
void EnableScrollBar(uint sbFlags = SB_BOTH, uint arrowFlags = ESB ENABLE BOTH); 
Disables or enables one or both of the scroll bar arrows on the scroll bars associated with 
this window. sbFlags, which specifies the type of scroll bar, can be one of the Scroll Bar — 
constants (SB_CTL, SB_HORZ, SB_VERT, or SB_BOTH). By default, the arrows on both 
the horizontal and vertical scroll bars are either enabled or disabled. arrowFlags, which 
indicates whether the scroll bar arrows are enabled or disabled, can be one of the Enable 
Scroll Bar constants (ESB_ENABLE_BOTH, ESB DISABLE _LTUP, | 
ESB_DISABLE_RTDN, ESB_DISABLE_BOTH). By default, the arrows on both the 
horizontal and vertical scroll bars are enabled. 


See also SB_Xxxx ScrollBar Constants 


EnableTransfer 

void EnableTransfer(); 

Enables the transfer miechanisny: which allows state jae to be transferred between the | 
window and a transfer buffer. 


EnableWindow — 

virtual bool EnableWindow(bool enable); | 

Allows the given window to receive input from the keyboard of mouse. If enable is 
TRUE, the window can receive input. Use the munction IsWindowEnabled to determine if 
the window has been enabled. 


See also TWindow::IsWindowEnabled 


EnumProps 

int EnumProps(PROPENUMPROC proc); 
Enumerates all the items in the property list of the current window and passes them one - 
by one to the callback function indicated in proc. The process continues until every item 
has been enumerated or until proc returns Zero. proc holds the address of the callback 
function. 


EvChildinvalid 

void EvChildinvalid(HWND hWnd); 

Responds to a WM_CHILDINVALID message posted by a child edit control. Indicates 
that the contents of the child window are invalid. 
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EvCommand 

virtual LRESULT EvCommand(uint id, HWND hWndCti, uint notifyCode); 

WindowProc calls EoCommand to handle WM_COMMAND messages. id is the identifier 
of the menu item or control. hWndCil holds a value that represents the control sending 
the message. If the message is not from a control, it is 0. notifyCode holds a value that 
represents the control's notification message. If the message is from an accelerator, 
notifyCode is 1; if the message is from a menu, notifyCode is 0. 


Seealso TWindow::DefaultProcessing 


EvCommandEnable 

virtual void EvCommandEnable(TCommandEnableré& ce); 

Called by WindowProc to handle WM_COMMAND_ENABLE messages, EvCommand 
calls the CmXxxx command-handling function or calls DefaultProcessing to handle the 
incoming message. 


Seealso TWindow::DefaultProcessing, TCommandEnabler 


EvSysCommand 

void EvSysCommand(uint cmdType, TPoint& point); 

Responds to a user-selected command from the System menu or when the user selects 
the maximize or minimize box. Applications that modify the system menu must process 
EvSysCommand messages. Any EvSysCommand messages not handled by the application 
must be passed to DefWindowProc. The parameter cmdType can be one of the following 
system commands: 


SC_CLOSE Close the window. 

SC_HOTKEY Activate the specified window. 
SC_HSCROLL Scroll horizontally. 

SC_KEYMENU Retrieve a menu through a keystroke. 
SC_MAXIMIZE (or SC_ZOOM) Maximize the window. 
SC_MINIMIZE (or SC_ICON) Minimize the window. 
SC_MOUSEMENU | Retrieve a menu through a mouse click. 
SC_NEXTWINDOW Move to the next window. 
SC_PREVWINDOW Move to the previous window. 
SC_SCREENSAVE Execute the specified screen saver. 
SC_SIZE Size the window | 
SC_TASKLIST Activate the Windows Task Manager. 
SC_VSCROLL Scroll vertically. 


In the following example, a either processes system messages or calls 
DefaultProcessing: 


void MyWindow: :EvSysCommand(uint cmdType, TPoint&) 
{ 
switch (cmdType& OxFFFO) { 
case SC_MOUSEMENU: 
case SC_KEYMENU: 
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break; 
default: 
DefaultProcessing(); 


} | | 
See also TWindow::DefaultProcessing 


FirstThat 

TWindow* FirstThat(TCondFunc test, void* paramList = 0); 

TWindow* FirstThat(TCondMemFunc test, void* paramList = 0); 

There are two FirstThat functions, both of which pass a pointer to an iterator function. 
The first FirstThat points to a nonmember function as its first parameter; the second 
FirstThat points to a member function instead. 


Both FirstThat functions iterate over the child list, calling a Boolean test function and 
passing each child window in turn as an argument (along with paramList). If a test call 
returns TRUE, the iteration is stopped and FirstThat returns the child window ee that 
was supplied to test. Otherwise, FirstThat returns 0. 


In the following example, GetFirstChecked calls FirstThat to obtain a pointer (p) to the first 
check box in the child list that is checked: 


bool IsThisBoxChecked(TWindow* p, void*) { 
return ((TCheckBox*)p)->GetCheck() == BF_CHECKED; 
| 
TCheckBox* TMyWindow: :GetFirstChecked() { 
return FirstThat (IsThisBoxChecked) ; 
} 


See also TCondFunc type 


FlashWindow 

bool FlashWindow(bool invert); 

FlashWindow changes the window from active to inactive or vice versa. If invert is 
nonzero, the window is flashed. If invert is 0, the window is returned to its original 
state—either active or inactive. 


ForEach | 

Form 1 void ForEach(TActionFunc action, void" paramList = 0); 
There are two ForEach functions. This ForEach takes a nonmember function as its first 
parameter; the other ForEach (see the following entry) takes a member function instead. 
This version of ForEach iterates over the child list, calling a nonmember function 
supplied as the action to be performed and passing each child window i in turn as the 
argument (along with paramList). 


In the following example, CheckAllBoxes calls ForEach, ee all the check boxes in the 
child list: 


void CheckTheBox(TWindow* p, void*) f 
( (TCheckBox* ) p) ->Check ( ) ; 
} 
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void CheckAl1Boxes() { 
ForEach (CheckTheBox) ; 
} 
void ForEach(TActionMemFunc action, void* paramList = 0); 
Refer to the previous ForEach description. The difference between the two ForEach 


members is that the first ForEach takes a nonmember function as a parameter and this 
ForEach takes a member function as a parameter. 


Seealso TActionFunc typedef, TActionMemFunc typedef 


ForwardMessage 

LRESULT ForwardMessage(bool send = true) 

Forwards the window's current message. Calls SendMessage if send is TRUE; otherwise 
calls PostMessage. 


LRESULT ForwardMessage(HWND hWnd, bool send = true); 
Forwards the window's current message to another HWND. Calls SendMessage if send is 
true; otherwise calls PostMessage. 


See also TWindow::PostMessage 


~ GetActiveWindow 


static HWND GetActiveWindow(): | | 
GetActiveWindow retrieves the handle of the active window. Returns 0 if no window is 
associated with the calling thread. 


GetApplication 

TApplication* GetApplication()const; 

Gets a pointer to the TApplication object associated with this. Use GetApplication to obtain 
access to data and functions in the TApplication object. 


GetCapture 
static HWND GetCapture(); 
Returns the handle of the window that has captured the mouse. 


GetCaretBlinkTime 
Static uint GetCaretBlinkTime(); | 
GetCaretBlinkTime retrieve the caret blink rate in milliseconds. 


See also TWindow::SetCaretBlinkTime 
GetCaretPos 
Static void GetCaretPos(TPoint& point); 


GetCaretPos gets the position of the caret in the coordinates of the client window. point 
refers to the structure that receives the client coordinates of the caret. 


See also TWindow::SetCaretPos 


GetClassLong 
long GetClassLong(int index) const; 
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GetClassLong retrieves the 32-bit value about the window class. If unsuccessful, returns 
0. Depending on the value of index, GetClassLong can retrieve the following information: 


/GCL_CBCLSEXTRA _ "Size in bytes of memory associated with this class 
GCL_CBWINDEXTRA Size of extra window memory associated with each window 
GCL_HBRBACKGROUND Handle of the background brush associated with the class 
GCL_HCURSOR | Handle of the cursor 
GCL_HICON Handle of the icon 
GCL_HMODULE -Handle of the module that registered the class — 
GCL_MENUNAME | Address of the menu name string 
GCL_STYLE The style bits associated with a window class 
GCL_WNDPROC Address of the window procedure associated with this class 


Seealso Twindow::SetClassLong 


GetClassWord 

uint16 GetClassWord(int index) const; 

GetClassWord gets a 16-bit value containing information about the class or style of the 
window. If unsuccessful; returns 0. Depending on the value of index, GetClassWord can 
retrieve the following information: 


GCW_CBCLSEXTRA Number of additional class information 
GCW_CBWINDEXTRA Number of bytes of additional window information 
GCW_HBRBACKGROUND _ Handle of the background brush 

GCW_HCURSOR Handle of the cursor 

GCW_HICON Handle of the icon 

GCW_HMODULE Handle of the module 

GCW_STYLE The style bits associated with a window class 


Seealso TWindow::SetClassWord 


| GetClientRect 
Form1  TRect GetClientRect() const; 
GetClientRect gets the coordinates of the window's client area (the area in a window you 
can use for drawing). 


Form2 void GetClientRect(TRect& rect) const; 
Gets the coordinates of the window's client area and then copies them into the object 
referred to by TRect. 


GetCursorPos 

static void GetCursorPos(TPoint& pos): 

GetCursorPos retrieves the cursor's current position (in window screen coordinates) and 
copies the values into the structure pointed to by TPoint. 
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GetDesktopWindow 
static HWND GetDesktopWindow(); 
GetDesktopWindow returns a handle to the desktop window. 


GetDigCtrilD 
int GetDigCtrlID() const; 
GetDlgCtrlID returns the ID of the control. 


GetDigitem 
HWND GetDigltem(int childld) const: 
GetDigltem retrieves the handle of a control specified by childId. 


Seealso TWindow::GetDlgItemInt 


GetDigitemint 

uint GetDigltemint(int childld, bool *translated = 0,bool isSigned = true) const; 

GetDlgItemInt retrieves the text of a control specified by childId. translated points to the 
variable that receives the translated value. isSigned indicates that the retrieved value is 
signed (the default). 


Seealso TWindow::GetDlgltem 


GetDigitemText 

uint GetDigltemText(int childld, char far* text, int max) const; 

GetDlglItemText retrieves the text of a control specified by childId. text points to the text 
buffer to receive the text. max specifies the maximum length of the caption, which is 
truncated if it exceeds this length. 


Seealso TWindow::SetDlgItemText 


GetFirstChild 

TWindow* GetFirstChild() 

Returns a pointer to the first child window, which is the first window created, in the 
interface object's child list. 


Seealso TWindowAttr struc 


GetFocus 

static HWND GetFocus(); 

Gets a handle to the window that has the focus. Use the function SetFocus to set the 
keyboard focus to this window. 


Seealso TWindow::SetFocus 


GetHWndState 

void GetHWndState(); 

Copies the style, coordinate, and the resource id (but not the title) from the existing 
HWnd into the ObjectWindows' TWindow members. 


Getid 
int Getld(); 
Returns Attr.Id, the ID used to find the window ina specified parent's child list. 


Seealso TWindowAttr struct 
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- GetModule 


TModule* GetModule() const; 
Returns a pointer to the module object. 


GetLastActivePopup 
HWND GetLastActivePopup() const; 
Returns the last active pop-up window in the list. 


GetLastChild 
TWindow* GetLastChild(); 
Returns a pointer to the last child window in the interface object's child list. 


GetMenu 

HMENU GetMenu() const; | 
GetMenu returns the handle to the menu of the indicated window. If the window has no 
menu, the return value is 0. 7 


Seealso TWindow::SetMenu 


GetNextDigGroupltem 

HWND GetNextDigGroupltem(HWND hWndCtrl, bool previous = false) const; 

GetNextDlgGroupltem returns either the next or the previous control in the dialog box. 
hWndCtrl identifies the control in the dialog box where the search begins. If previous is 
0, GetNextDlgGrouplItem searches for the next control; if nonzero, it searches for the 
previous control. 


GetNextDigTabltem 

HWND GetNextDigTabltem(HWND HWndCtrl, bool previous = false) const; 

GetNextDIlgTabltem returns the handle of the first control that lets the user press the TAB 
key to move to the next control (that is, the first control with the WS_TABSTOP style 
associated with it). hWndCirl identifies the control in the dialog box where the search 
begins. If previous is 0, GetNextDlgGroupltem searches for the next control; if nonzero, it 


searches for the previous control. 


GetNextWindow 

HWND GetNextWindow(uint dirFlag) const; 

GetNextWindow finds the handle associated with either the next or previous window in 
the window manager's list. dirFlag specifies the direction of the search. Under the Win 
32 API, GetNextWindow returns either the next or the previous window's handle. If the 
application is not running under Win32, GetNextWindow returns the next window's 
handle. 


GetWindowPtr 

TWindow* GetWindowPtr(HWND hWnd); — 

This version of GetWindowPtr actually calls TApplication's GetWindowPtr on the 
application associated with this window. Then, given the handle to this window 
(hWnd), GetWindowPtr returns the TWindow pointer associated with ths window. 


Seealso TApplication:GetWindowPtr 


GetParent 
HWND GetParent() const; 
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GetParent retrieves the handle of the parent window. If none exists, returns 0. 


See also TWindow::SetParent 


GetProp 

HANDLE GetProp(uinti6 atom) const; 

GetProp returns a handle to the property list of the specified window. atom contains a 
value that identifies the character string whose handle is to be retrieved. If the specified 
string is not found in the property list for this window, returns NULL. 


HANDLE GetProp(const char far* string) const; 

GetProp returns a handle to the property list of the specified window. Unlike the 
previous GetProp function, string points to the string whose handle is to be retrieved. If 
the specified string is not found in the property list for this window, returns NULL. 


See also TWindow::SetProp 


GetScrollPos 

int GetScrollPos(int bar) const; 

GetScrollPos returns the thumb position in the scroll bar. The position returned is relative 
to the scrolling range. If bar is SB_CTL, it returns the position of a control in the scroll 
bar; if bar is SB_HORZ, it returns the position of a horizontal scroll bar; if bar is 
SB_VERT, it returns the position of a vertical scroll bar. 


Seealso TWindow::SetScrollPos, SB_Xxxx Scroll Bar Constants 


GetScrollRange 

void GetScrollRange(int bar, int& minPos, int& maxPos) const; 

GetScrollRange returns the minimum and maximum positions in the scroll bar. If bar is 
SB_CTL, it returns the position of a control in the scroll bar; if bar is SB_HORZ, it returns 
the position of a horizontal scroll bar; if bar is SB_VERT, it returns the position of a 
vertical scroll bar. minPos and maxPos hold the lower and upper range, respectively, of 
the scroll bar positions. If there are no scroll bar controls ¢ or if the scrolls are non- 
standard, minPos and maxPos are zero. 


Seealso TWindow::SetScrollRange, SB_Xxxx Scroll Bar Constants 


GetSysModalWindow 
static HWND GetSysModalWindow(); 
Retrieves the handle of the system-modal window. 


Seealso T'Window::SetSysModalWindow 


GetSystemMenu 

HMENU GetSystemMenu(bool revert = false) const; 

GetSystemMenu returns a handle to the system menu so that an application can access 
the system menu. 


GetThunk 

WNDPROC GetThunk()const; 

Gets the instance thunk, a small piece of code created for use with exported callback 
functions. (A callback function is a function that exists within a program but is called 
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from outside the program es a Windows aveaty routine, for example, a dialog box. | 
function. ) | 


7 GetTopWindow 

HWND GetTopWindow()const; 

GetTopWindow returns a handle to the top window oe owned a this parent 
window. If no oo exist, GetTopWindow returns 0. 


—GetUpdateRect 

bool GetUpdateRect(TRect& rect, bool erase = true) const; 

GetUpdateRect retrieves the screen coordinates of the rectangle that encloses the updated 
region of the specified window. erase specifies whether GetUpdateRect should erase the 
background of the updated region. | 


Seealso TWindow::RedrawWindow 


GetUpdateRgn 

bool GetUpdateRgn(TRegion& rgn, bool erase = true) const; 

GetUpdateRgn copies a window's update region into a region specified by region. If erase 
is true, GetUpdateRgn erases the background of the updated region and redraws 
nonclient regions of any child windows. If erase is false, no redrawing occurs. 


If the call is successful, GetUpdateRgn returns a value indicating the kind of region that 
was updated. If the region has no overlapping borders, it returns SIMPLEREGION; if 
the region has overlapping borders, it returns COMPLEXREGION; if the region is 
empty, it returns NULLREGION,; if an error occurs, it returns ERROR. 


See also TWindow::RedrawWindow 


GetWindow 

HWND GetWindow (uint cmd) const; 

Returns the handle of the window that has the indicated relationship to this window. 
cmd , which indicates the type of relationship to be obtained, can be one of the following 
values: 


See also TApplication:GetWindowPtr 


GetWindowFont 

HFONT GetWindowFont(); 

Gets the font the control uses to draw text. The return value is a handle of the font the 
control uses. If a system default font is being used, GetWindowFont returns NULL. 


GetWindowLong 

long GetWindowLong(int index) const; 

GetWindowLong retrieves information about the window depending on the value stored 
in index. The values returned, which provide information about the window, include the 
following GWL_Xxxx window style constants: 


GWL_STYLE © | The window style (position, device context creation, size, and so on) 
GWL_WNDPROC - The address of the window procedure being processed 
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In the case of the dialog box, additional information can be retrieved, such as: 


DWL_DLGPROC The address of the procedure processed by the dialog box 
DWL_MSGRESULT The value that a message processed by the dialog box returns 
DWL_USER Additional information that pertains to the application, such as pointers or 


handles the application uses. 


Seealso TWindow::GetClassLong 


GetWindowPlacement 

bool GetWindowPlacement(WINDOWPLACEMENT* place) const; 

GetWindowPlacement retrieves display and placement information (normal, minimized, 
and maximized positions) about the window and stores that information in the 
argument, place . 


See also —TWindow::SetWindowPlacement, TWindow::Show 


GetWindowRect 
void GetWindowRect(Trect& rect) const; 
Gets the screen coordinates of the window's rectangle and copies them into rect. 


TRect GetWindowRect() const; 
Gets the screen coordinates of the window's rectangle. 


See also TWindow::GetClientRect 


GetWindowTask 
HTASK GetWindowTask() const; 
Returns a handle to the task that created the specified window. 


GetWindowText 

int GetWindowText(char far* string, int maxCount) const; 

GetWindowText copies the window's title into a buffer pointed to by string. maxCount 
indicates the maximum number of characters to copy into the buffer. A string of 
characters longer than maxCount is truncated. GetWindowText returns the length of the 
string or 0 if no title exists. 


Seealso TWindow::SetWindowText, TWindow::GetWindowTextTitle, 
TWindow::SetCaption 


GetWindowTextLength 

int GetWindowTextLength() const; 

GetWindowTextLength returns the length, in characters, of the specified window's title. If 
the window is a control, returns the length of the text within the control. If the window 
does not contain any text, GetWindowTextLength returns 0. 


See also TWindow::SetWindow Text 


GetWindowTextTitle 
void GetWindowTextTitle(); 
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Updates the TWindow Title data member from the current window's caption. 
GetWindowTextTitle is used to keep Title synchronized with the actual window state 
when there is a possibility that the state might have changed. 


Seealso TWindow::SetCaption, TWindow::Title 


GetWindowWord 

uinti6 GetWindowWord(int index) const; . | 
GetWindowWord retrieves information about this window depending on the value of 
index. GetWindowWord returns one of the following values that indicate information 
about the window: 


GWW_HINSTANCE The instance handle of the module owning the window 
GWW_HWNDPARENT The handle of the parent window 
GWW_ID The ID number of the child window 


See also TWindow::GetWindowLong, TWindow::SetWindowWord, 
_ TWindow::SetParent — 


HandleMessage 
LRESULT HandleMessage(uint msg, WPARAM wParam = 0, LPARAM IParam = 0); 

Handles message sent to a window. HandleMessage can be called directly to handle 
Windows messages without going through SendMessage. 


See also 9TWindow::SendMessage 


HideCaret 
void HideCaret(); | 
HideCaret removes the caret from the specified desiy screen. The caret is hidden only if 
the current task's window owns the caret. Although the caret is not visible, it can be 

displayed again using ShowCaret | 


See also TWindow::CreateCaret, TWindow::ShowCaret 


HiliteMenultem 

bool HiliteMenultem(HMENU hMenu, uint idltem, uint hilite); 

HiliteMenultem either highlights or removes highlighting from a top-level item in the 
menu. idItem indicates the menu item to be processed. hilite (which contains a value that 
indicates if the idItem is to be highlighted or is to have the highlight removed) can be one 
or more of the following constants: 


MF_BYCOMMAND The idItem parameter contains the menu item's identifier. 


MF_BYPOSITION The idItem parameter contains the zero-based relative position of the menu item. 
MF_HILITE Highlights the menu item. If this value is not specified, highlighting i is removed 

_ from the item. 
MF_UNHILITE Removes the menu item's highlighting. 
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If the menu is set to the specified condition, HiliteMenultem returns true; otherwise, 
returns false. 


Seealso TWindow::GetMenu 


HoldFocusHWnd 

virtual bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain); 

Responds to a request by a child window to hold its HWND when it is losing focus. 
Stores the child's HWND in HwndkRestoreFocus. 


Seealso TFrameWindow::HoldFocusHwnd 


HWND() 

operator HWND()const; 

Allows a TWindow& to be used as an HWND in Windows API calls by providing an 
implicit conversion from TWindow to HWND. 


IdleAction 

virtual bool IdleAction(long idleCount); 

Called when no messages are waiting to be processed, IdleAction performs idle 
processing as long as true is returned. idleCount specifies the number of times idleAction 
has been called between messages. 


Invalidate 

void Invalidate(bool erase = true); 

Invalidates (mark for painting) the entire client area of a window. The window then 
receives a message to redraw the window. By default, the background of the client area 
is marked for erasing. 


See also TWindow::Validate, TWindow::InvalidateRect 


InvalidateRect : 

void InvalidateRect(const TRect&, bool erase = true);: 

Invalidates a specified client area. By default, the background of the client area to be 
invalidated is marked for erasing. 


See also TWindow::ValidateRect, TWindow::Invalidate 


invalidateRgn 

void InvalidateRgn(HRGN hRgn, bool erase = true); 

InvalidateRgn invalidates a client area within a region specified by the hRgn parameter 
when the application receives a WM_PAINT message. The region to be invalidated is 
assumed to have client coordinates. If iRgn is 0, the entire client area is included in the 
region to be updated. The parameter erase specifies whether the background with the 
update region needs to be erased when the region to be updated is determined. If erase is 
true, the background is erased; if erase is false, the background is not erased when the 
Paint function is called. By default, the background within the region is marked for 
erasing. 


Seealso TWindow::ValidateRgn, TWindow::Paint 


IsChild 
bool IsChild(HWND hWnda) const; 
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IsChild is TRUE if the window is a child window or a descendant window of this 
window. A window is considered a child window if it is the direct descendant of a given 
parent window and the parent window is in a chain of windows leading from the 
original overlapped or pop-up window down to the child wee hWnd identifes the 
window to be tested. 


IsDigButtonChecked 
uint IsDigButtonChecked(int buttonld) const; 
IsDIgButtonChecked indicates if the child button specified in the integer parameter, 
buttonld , is checked or if a button is grayed, checked or neither. If the return value is 0, 

_ the button is unchecked. If the return value is 1, the button is checked. If the return value 
is 3, the button state is undetermined. This function sends a BM_GETCHECK message 
to the specified button control. 


IsFlagSet 

bool IsFlagSet(TWindowFlag mask); 

Returns the state of the bit flag in Attr.Flags whose mask is supplied. Returns true if the 
bit flag is set, and false if not set. 


See also TWindowAttr struc 


isiconic 
bool Islconic() const; 
Is TRUE if window is iconic or minimized. 


IsWindow 
bool IsWindow() const; 
Is TRUE if an HWND is being used. 


IsWindowEnabled 

bool IsWindowEnabled(); 

Is true if the window is enabled. Use the function EnableWindow to enable or disable a 
window. 


See also TWindow::EnableWindow 


IsWindowVisible 
bool IsWindowVisible() const; 


Is true if the window is visible. By default, TWindow’s constructor sets the window style 
attribute (WS_VISIBLE) so that the window is visible. 


IsZoomed 
bool IsZoomed() const; 
Is true if window is zoomed or maximized. 


KillTimer 

bool KillTimer(uint timerld); 

KillTimer gets rid of the timer and removes any WM_TIMER messages from the 
message queue. timerId contains the ID number of the timer event to be killed. 


See also —TWindow::SetTimer — 
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LockWindowUpdate 

bool LockWindowUpdate(); ? 

LockWindowUpdate prevents or enables window drawing for one window at a time. If 
the window is locked, returns true; otherwise, returns false, which indicates an error 
occurred or some other window is already locked. 


If there is any attempted drawing attempted within a locked window or locked child 
windows, the extent of the attempted operation is saved within a bounding rectangle. 
When the window is then unlocked, the area withing the rectangle is invalidated. This 
causes a paint message to be sent to this window. If any drawing occurred while the 
window was locked for updates, the area is invalidated. 


MapWindowPoints | 

void MapWindowPoints(HWND hWndTo, TPoint* points, int count) const; 

MapWindowPoints maps a set of points in one window to a relative set of points in 
another window. hWrdTo specifies the window to which the points are converted. 
points points to the array containing the points. If hWndTo is 0, the points are converted 
to screen coordinates. count specifies the number of points structures in the array. 


MessageBox 

int MessageBox(const char far* text,const char far* caption = 0, uint type = MB_OK); 

Creates and displays a message box that contains a message (text), a title (caption), and 
icons or push buttons (type). If caption is 0, the default title is displayed. Although type is 
set to one push button by default, it can contain a combination of the MB_Xxxx message 
constants. This function returns one of the following constants: 


IDABORT User selected the abort button. 
IDCANCEL User selected the cancel button. 
IDIGNORE User selected the ignore button. 
IDNO User selected the no button. 
IDOK User selected the OK button 
IDRETRY User selected the retry button. 
IDYES - User selected the yes button. 


If BWCC is already enabled, then the message box will be a BWCC enabled. If CTRL 3D 
is already enabled, then the message box will be CTRL 3D enabled. If neither BWCC nor 
CTRL 3D is enabled, the message box will be displayed as a standard windows message 
box. 


See also ‘T’Window::PostMessage, MB_Xxxx message constants 


MoveWindow 

void MoveWindow(int x, int y, int w, int h, bool repaint = false); 

MoveWindow repositions the specified window. x and y specify the new upper left 
coordinates of the window; w and h specify the new width and height, respectively. If 
repaint is false, the window is not repainted after it is moved. 


void MoveWindow(const TRect& rect, bool repaint = false); 
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MoveWindow repositions the window. rect references the left and top coordinates and 
the width and height of the new screen rectangle. If repaint is FALSE, the window is not 
repainted after it is moved. 


See also TWindow::RedrawWindow 


Next 
TWindow* Next(); - 
Returns a pointer to the next sibling window in the window's sibling list. 


See also TWindow::Previous 


NumChildren 
unsigned NumChildren(); | 
Returns the number of child windows of the window. 


OpenClipboard 

TClipboard& OpenClipboard(); 

Opens the clipboard and prevents other application from changing the contents of the 
clipboard. This function fails if another window has already opened the clipboard. 


Paint 

virtual void Paint(TDC& dc, bool erase, TRect& rect); 

Repaints the client area (the area you can use for drawing) of a window. Called by base 
classes when responding to a WM_PAINT message, Paint serves as a placeholder for 
derived types that define Paint member functions. Paint is called by EvPaint and 
requested automatically by Windows to redisplay the window's contents. dc is the paint 
display context supplied to text and graphics output functions. The supplied reference 
to the rect structure is the bounding rectangle of the area that requires painting. erase 
indicates whether the background needs erasing. 


PostMessage 

bool PostMessage(uint msg, WPARAM wParam = 0, LPARAM IParam=0) const; 

PostMessage posts a message (msg) to the window in the application's message queue. It 
returns without waiting for the corresponding window to process the message. 


See also 9TWindow::ForwardMessage, TWindow::MessageBox 


PerformCreate 
virtual void PerformCreate(int menuOrld); | 

_ PerformCreate is called from within Create to perform the final step in creating an 
MS_Windows interface element to be associated with an ObjectWindows window. 
PerformCreate can be overridden to provide alternate HWND create implementation. 


See also TWindow::Create 


PreProcessMsg 

virtual bool PreProcessMsg(MSG& msg); 

PreProcessMsg allows preprocessing of queued messages prior to dispatching. If you 
override this method in a derived class, be sure to call the base class's PreProcessMsg 
because it handles the translation of accelerator keys. When nonzero is returned, 
message processing stops. 
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Seealso TApplication::ProcessAppMsg 


Previous 
TWindow* Previous(); 
Returns a pointer to the previous window in the window's sibling list. 


Seealso —TWindow::Next 


ReceiveMessage 

LRESULT ReceiveMessage(uint msg, WPARAM wParam = 0, LPARAM IParam = 0); 

Called from StdWndProc, RecetveMessage is the first member function called when a 
message is received. It calls HandleMessage from within the try block of the exception- 
handling code. In this way, exceptions can be caught and suspended before control is 
returned to exception-unsafe Windows code. 


Seealso TWindow::HandleMessage 


RedrawWindow 

bool RedrawWindow(TRect* update, HRGN hUpdateRgn, uint redrawFlags = RDW_INVALIDATE | 
RDW_UPDATENOW | RDW_ERASE); 

RedrawWindow redraws the rectangle specified by update, and the region specified by 
hUpdateRgn. redrawFlags can be a combination of one or more of the following 
-RDW_Xxxx Redraw Window constants used to invalidate or validate a window. 


These values invalidate a window: 


RDW_ERASE When the window is repainted, it receives a WM_ERASEBKGND 
message. If RDW_INVALIDATE is not also specified, this flag has no 
effect. 

RDW_FRAME Any part of the non-client area of the window receives a 
WM_NCPAINT message if it intersects the region to be updated. 

RDW_INTERNALPAINT A WM_PAINT message is posted to the window whether or not it 

: contains an invalid region. 
RDW_INVALIDATE Invalidates either hUpdateRgn or update. In cases where both are 0, the 


entire window becomes invalid. 


These values validate a window: 


RDW_NOERASE The window is prevented from receiving any WM_ERASEBKGND 
messages. 
RDW_NOFRAME The window is prevented from receiving any WM_NCPAINT 


messages. The flag ROW_VALIDATE must also be used with this flag. 


RDW_NOINTERNALPAINT The window is prevented from receiving internal WM_PAINT 
messages, but does not prevent the window from receiving 
WM_PAINT messages from invalid regions. 


RDW_VALIDATE Validates update and hUpdateRgn. However, if both are 0, the entire 
window area is validated. The flag does not have any effect on internal 
WM_PAINT messages. 
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These flags control when the window is repainted: 


RDW_ERASENOW Before the function returns, the specified windows will receive | 
WM_NCPAINT and WM_ERASEBKGND messages. 
RDW_UPDATENOW Before the function returns, the specified windows will receive 
7 WM_NCPAINT, WM_ERASEBKGND, as well as WM_PAINT 
messages. 


Seealso TWindow::GetUpdateRect 

Register | 

virtual bool Register(); 

Registers the Windows registration class of this window, if this window is not already 
registered. Calls GetClassName and GetWindowClass to retrieve the Windows registration 


class name and attributes of this window. ees returns true if this window is 
registered. 


See also T’'Window::GetClassName, TWindow: -GetWindowClass, WNDCLASS struct 


RegisterHotKey 

bool RegisterHotKey(int idHotKey, uint modifiers, uint virtKey); 

RegisterHotKey registers a hotkey ID with the current application. modifiers can be a 
combination of keys that must be pressed to activate the specified hotkey, for example, 
HOTKEYF_SHIFT, HOTKEYF_CONTROL, and HOTKEYF_ALT. 


See also TWindow::UnRegisterHotKey 


ReleaseCapture 
static void ReleaseCapture(); 
Releases the mouse capture from this window. 


RemoveProp 

Form 1 HANDLE RemoveProp(uint16 atom) const; 
RemoveProp removes the property specified by atom from the application’ s property list. 
atom indicates the string to be removed. Returns the handle of the given string or NULL 
if no string exists in the window's property list. 


Form 2 HANDLE RemoveProp(const char far* str) const; 
RemoveProp removes the property specified by str, a null-terminated string, from the 
application's property list. Returns the handle of the given string or NULL if no string 
exists in the window's property list. 
See also T'Window::GetProp | 


ScreenToClient 

void ScreenToClient(TPoint& point) const: 

ScreenToClient uses the screen coordinates specified i in point to calculate client window’ S 
coordinates and then place the new coordinates into point. 


ScrollWindow | 
void ScrollWindow(int dx, int dy, const TRect* scroll = 0, const TRect far* clip = 0); 
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ScrollWindow scrolls a window in the vertical (dx) and horizontal (dy) directions. TRect 
indicates the area to be scrolled. If 0, the entire client area is scrolled. clip specifies the 
clipping rectangle to be scrolled. Only the area within clip is scrolled. If clip is 0, the 
entire window is scrolled. 


See also TWindow::ScrollWindowEx 


ScrollWindowEx 

void ScrollWindowEx(int dx, int dy, const TRect far* scroll = 0, aoe TRect far* clip = 0, HRGN hUpdateRgn = 
0, TRect far* update = 0, uint flags = 0); 

ScrollWindowEx scrolls a window in the vertical (dx) and horizontal (dy) directions. scroll 
indicates the area to be scrolled. If 0, the entire client area is scrolled. clip specifies the 
clipping rectangle to be scrolled. Only the area within clip is scrolled. If clip is 0, the 
entire window is scrolled. update indicates the region that will receive the boundaries of 
the area that becomes invalidated as a result of scrolling. flags, which determines how 
the window's children are scrolled, can be one of the following SW_Xxxx Scroll 
Window constants: 


_ Description — 26 oe a a oe ee 
-SW_ERASE - Erases the invalidated region anise sending an erase ha on message to 
the window indicated by the SW_INVALIDATE flag value. 
SW_INVALIDATE Invalidates the region indicated by the hUpdate parameter. 
SW_SCROLLCHILDREN Scrolls all the child window intersecting the rectangle pointed to by the scroll 
parameter. 


Seealso TWindow::ScrollWindow, TWindow::Show 


SendDigitemMessage 
LRESULT SendDigltemMessage(int childld, uint msg, WRARAM wParam = 0, LPARAM |Param = 0); 
SendDigltemMessage sends a message (msg) to the control specified in childld. 


Seealso TWindow::SendMessage 


SendMessage 

LRESULT SendMessage(uint msg, WPARAM wParam = 0, LPARAM IParam = 0); 

SendMessage sends a message (msg) to a specified window or windows. After it calls the 
window procedure, it waits until the window procedure has processed the message 
before returning. 


See also TWindow::ChildBroadcastMessage, TWindow::HandleMessage, 
TWindow::SendDlgltemMessage 


SendNotification 

void SendNotification(int id, int notifyCode, HWND hCtl, uint msg = WM COMMAND); 

Repacks a command message (msg) so that a child window (hC?l) can send a message to 
its parent regardless of whether this is a WIN16 or WIN32 application. 


SetActiveWindow 

HWND SetActiveWindow(); | 
SetActiveWindow activates a top-level window. Returns a handle to the previously active 
window. 
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SetBkgndColor 

void SetBkgndColor(uint32 color); 

Sets the background color (color) for the window. You can also get the current color of an 
element displayed on the screen. For example, 


layout -> SetBkgndColor (GetSysColor (COLOR_APPWORKSPACE) ) ; 


uses one of the Windows COLOR values (in this case, the color of multiple document 
interface applications (MDI). 


Seealso TWindow::BkgndColor 


— SetCaption 
void SetCaption(const char far* title); . 


Copies title to an allocated string pointed to by title. Sets the caption of the interface 
element to title. Deletes any previous title. 


See also TWindow::GetWindow TextTitle, TWindow::Title 


SetCapture 

HWND SetCapture(); 

Sets the mouse capture to sg current window. All mouse input is directed to this 
window. | 


SetCaretBlinkTime 
static void SetCaretBlinkTime(uint16 miliSecs): 
SetCaretBlinkTime sets the caret blink rate in milliseconds. 


Seealso TWindow::GetCaretBlinkTime 


SetCaretPos 

Form1 _ static void SetCaretPos(int x, int y); 
SetCaretPos sets the position of the caret in the coordinates of the client window. x and y 
indicate the client coordinates of the caret. 


Form 2 — static void SetCaretPos(const TPoint& pos); 
SetCaretPos sets the position of the caret in the coordinates of the client window. pos 
indicates the client coordinates of the caret. 


See also TWindow: :;GetCaretPos, TWindow: ‘ShowCaret 


SetClassLong 

long SetClassLong(int index) const; 

SetClassLong sets the long value at the specified offset (index). Depending on the value of 
index, SetClassLong sets a handle to a background brush, cursor, icon, module, menu, 
window function, or extra class bytes. 


See also TWindow::GetClassLong 
SetClassWord 
uintl6 SetClassWord(int index, uint16 newWord); 


SetClassWord sets the word value at the specified offset (index). Depending on the value 
of index , SetClassLong sets the number of bytes of class information, of additional 
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window information, or the style bits. Unlike SetClassLong, SetClassWord uses one of the 
following GCW_xxxx Class Word constants: 


Nalue 2  e Meaning — : — 
| GCW_HBRBACKGROUND > Sets a handle for a background brush: 
GCW_HCURSOR Sets a handle of a cursor. 
GCW_HICON Sets a handle of an icon. 
GCW_STYLE Sets a style bit for a window class. 


Seealso TWindow::GetClassWord 


SetCursor 

bool SetCursor(TModule* module, TResld resid); 

Sets the cursor position for the window using the given module and Resld. If the module 
parameter is 0, CursorResId can be one of the IDC_xxxx constants that represent 
different kinds of cursors. See the data member for a list of these cursor values. If the 
mouse is over the client area, SetCursor changes the cursor that is displayed. 


Seealso TWindow::GetCursorPos, TWindow::CursorResId 


SetDigitemint 

void SetDigltemint(int childld, uint value, bool isSigned = true) const; 

SetDIgItem sets the child window with the Id (childId) in the window to the integer value 
specified in value. If isSigned is true, the value is signed. 


See also TWindow::GetDlgltem 


SetDigitemText 

void SetDigitemText(int childld, const char far* text) const; 

SetDigltemText sets the text of a child with Id. text points to the text buffer containing the 
window caption or text that is to be copied into the child window caption or text. 


Seealso TWindow::GetDlgltemText 


setDoctitle 

virtual bool SetDocTitle(const char far* docname, int index); 

Stores the title of the document (docname). index is the number of the view displayed in 
the document's caption bar. In order to determine what the view number should be, 
SetDocTitle makes two passes: the first pass checks to see if there's more than one view, 
and the second pass, if there is more than one view, assigns the next number to the view. 
If there is only one view, index is 0, and therefore, the document doesn't display a view 
number. When TDocument’s checking to see if more than one view exists, index is —1. In 
such cases, only the document's title is displayed in the caption bar. 


SetDocTitle returns true if there is more than one view, and if TDocument displays the 
number of the view passed in index. 


SetFlag 

void SetFlag(TWindowFlag mask); 

If TRUE is supplied, the bits in Attr.Flags in Mask are set. Otherwise, the bit is cleared. 
Mask can be any one, or a combination, of the wfXxxx constants. 
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Seealso TWindow::IsFlagSet, TWindow: Flag enum 


SetFocus 

HWND SetFocus(); 

Sets the keyboard focus to current window and activates the window that receives the 
focus by sending a WM_SETFOCUS message to the window. All future keyboard input 
is directed to this window, and any previous window that had the input focus loses it. If 
successful, returns a handle to the window that has the focus; otherwise, returns NULL. 


See also. TWindow::GetFocus 


SetMenu 

bool SetMenu(HMENU hMenu); 

Sets the specified window's menu to the menu indicated by hMenu. If hMenu is 0, the 
window's current menu is removed. SetMenu returns 0 if the menu remains unchanged; 
otherwise, it returns a nonzero value. 


Seealso TWindow::GetMenu, TMDIFrame::SetMenu 


SetModule 
void SetModule(TModule* module); 
Sets the default module for this window. © 


See also TWindow::GetModule 


SetNext 
void SetNext(TWindow* next); 
Sets the next window in the one list. 


SetParent 

virtual void SetParent(TWindow* newParent); 

Sets the parent for the specified window by setting Parent to the specified new Parent 
window object. Removes this window from the child list of the previous parent 
window, if any, and adds this window to the new parent's child list. 


Seealso TWindow::GetParent 


SetProp 

bool SetProp(uinti6 atom, HANDLE data) const; 

Adds an item to the property list of the specified window. atom contains a value that 
identifies the data entry to be added to the property list. 


bool SetProp(const char far* str, HANDLE data) const; 
Adds an item to the property list of the specified window. str points to the string used to 


_ identify the entry data to be added to the property list. 


See also TWindow::GetProp 


| SetRedraw 


void SetRedraw(bool redraw); 
Sends a WM_SETREDRAW message to a window so that changes can be redrawn 
(redraw = true) or to prevent changes from being redrawn (redraw = false). 
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SetScrollPos 

int SetScrollPos(int bar, int pos, bool redraw = true); 

SetScrollPos sets the thumb position in the scroll bar. bar identifies the position 
(horizontal, vertical, or scroll bar control) to return and can be one of the SB_xxxx scroll 
bar constants. 


Seealso TWindow::GetScrollPos, SB_Xxxx Scroll Bar Constants 


SetScrollRange 

void SetScrollRange(int bar, int minPos, int maxPos, bool redraw = true); 

SetScrollRange sets the thumb position in the scroll bar. bar identifies the position 
(horizontal, vertical, or scroll bar control) to set and can be one of the SB_xxxx scroll bar 
constants. minPos and maxPos specify the lower and upper range, respectively, of the 
scroll bar positions. 


Seealso TWindow::GetScrollRange, TWindow::SetScrollRange, SB_Xxxx Scroll Bar 
Constants 


SetSysModalWindow 
HWND SetSysModalWindow(); 
Makes the indicated window a system-modal window. 


Seealso TWindow::GetSysModalWindow 


SetTimer 

uint SetTimer(uint timerld, uint timeout, TIMERPROC proc = 0); 

SetTimer creates a timer object associated with this window. timerID contains the ID 
number of the timer to be created, timeout specifies the length of time in milliseconds, 
and proc identifies the address of the function that's to be notified when the timed event 
occurs. If proc is 0, WM_TIMER messages are placed in the queue of the application that 
called SetTimer for this window. 


Seealso TWindow::KillTimer 


SetTransferBuffer 
void SetTransferBuffer(void* transferBuffer); 
Sets TransferBuffer to transfer Buffer. 


Seealso TWindow::Transfer, TWindow::TransferData 


SetWindowFont 

void SetWindowFont(HFONT font, bool redraw); 

Sets the font that a control uses to draw text. font, which specifies the font being used, is 
NULL if the default system font is used. If redraw is true, the control redraws itself after 
the font is set; if false, the control doesn't redraw itself. See the sample program, 
FILEBROW.CPP, for an example of how to set the font for a file browser list box. 


SetWindowLong 

long SetWindowLong(int index, long newLong); 

SetWindowLong changes information about the window. Depending on the value of 
index, SetWindowLong sets a handle to a background brush, cursor, icon, module, menu, 
or window function. The window style can be one of the GWL_xxxx values that 
represent styles. See GetWindowLong for a description of these values. 
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See also TWindow::GetWindowLong, TWindow::SetWindowWord | 


SetWindowPlacement 

bool SetWindowPlacement(const WINDOWPLACEMENT* place); 

SetWindowPlacement sets the window to a display mode and screen position. place points 
to a window placement structure that specifies whether the window is to be hidden, 
minimized or displayed as an icon, maximized, restored to a previous position, 
activated in its current form, or activated and displayed in its normal position. 


See also TWindow::GetWindowPlacement, TWindow::Show 


SetWindowPos 

void SetWindowPos(HWND hWndinsertAfter, const TRecté rect, uint flags); 

Changes the size of the window pointed to by rect. flags contains one of the 
SWP_XxxxSet Window Position constants that specify the size and position of the 
window. If flags is set to SWP_NOZORDER, SetWindowPos ignores the hWndInsertAfter 
parameter and retains the current ordering of the child, pop-up, or top-level windows. 


void SetWindowPos(HWND hWndinsertAfter, int x, int y, int w, int h, uint flags); 

Changes the size of the window pointed to by x, y, w, and h. flags contains one of the 
SWP_Xxxx Set Window Position constants that specify the size and position of the 
window. If flags is set to SWP_NOZORDER, SetWindowPos ignores the hWndInsertAfter 
parameter and retains the current ordering of the child, pop-up, or top-level windows. 


SWP_DRAWFRAME Draws a frame around the windo 


SWP_FRAMECHANGED _ Sends a message to the window to recalculate the window's size. If this flag 
is not set, a recalculate size message is sent only at the time the window’ S 


size is being changed. 
SWP_HIDEWINDOW Hides the window. 
SWP_NOACTIVATE - Does not activate the window. If this flag is not set, the window is activated 
| and moved to the top of the stack of windows. 
SWP_NOCOPYBITS Discards the entire content area of the client area of the window. If this flag 


is not set, the valid contents are saved and copied into the window after the 
window is resized or positioned. 


SWP_NOMOVE Remembers the window's current position. 
SWP_NOSIZE Remembers the window's current size. | 
SWP_NOREDRAW Does not redraw any changes to the window. If this flag is set, no 


repainting of any window area (including client, nonclient, and any 
window part uncovered as a result of a move) occurs. When this flag is set, 
the application must explicitly indicate if any area of the window is invalid 
and needs to be redrawn. 


SWP_NOZORDER Remembers the current Z-order (window stacking order). 
SWP_SHOWWINDOW Displays the window. 


See also TWindow::GetWindowPlacement 


SetWindowText 

void SetWindowText(const char far* str); 

SetWindowText sets the window's title to a buffer pointed to by str. taadenii indicates 
the number of characters to copy into the buffer. Note that this does not update this 
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Form 2 
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window's Title member. Use SetCaption if the window's Title member needs to be 
synchronized with the window's title. 


See also TWindow::GetWindow Text 


SetWindowWord 

uinti6 SetWindowWord(int index, uint16 newWord); 

SetWindowWord changes information about the window. index specifies a byte offset of 
the word to be changed to the new value (newWord). 


See also 9 TWindow::GetWindowWord, TWindow::SetWindowLong 


Show 

void Show(int cmdShow); 

After ensuring that the TWindow interface element has a valid handle, Show displays the 
TWindow on the screen in a manner specified by cmdShow, which can be one of the 
following SW_Xxxx show window constants: 


ShowCaret 

void ShowCaret(); | 
ShowCaret displays the caret in the specified shape in the active window at the current 
position. 


See also TWindow::CreateCaret, TWindow::HideCaret 


ShowOwnedPopups 
void ShowOwnedPopups(boo!l show); 
Shows or hides all owned popup windows according to the value of show. 


See also TWindow::Show 


ShowScrollBar 

void ShowScrollBar(int bar, boo! show = true); 

ShowScrollBar displays or hides the scroll bar. bar specifies whether the bar is a control 
itself or part of the window's nonclient area. If bar is part of the nonclient area, it can be 
one of the SB_xxxx scroll bar constants (specifically, SB_BOTH, SB_HORZ, or 
SB_VERT). If it is a control, it should be SB_CTRL. If show is true, the scroll bar is 
displayed; if false, it is hidden. 

See also TWindow::GetScrollRange, SB_Xxxx Scroll Bar Constants 

ShowWindow 

virtual bool ShowWindow(int cmdShow); 

Displays the window according to the value of cmdShow. See the function Show for a 


description of the SW_xxxx constants passed in cmdShow. Show is the preferred method 
of showing the window. 


See also TWindow::Show 


ShutDownWindow 
void ShutDownWindow(int retVal = 0); 
This inline version of ShutDownWindow calls the static version of ShutDownWindow. 


static void ShutDownWindow(TWindow* win, int retVal = 0); 
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This version of ShutDownWindow unconditionally shuts downa given window, calls 
Destroy on the interface element, and then deletes the interface object. Instead of using 
ShutDownWindow, you can call Destroy directly and then delete the interface object. 


SubclassWindowFunction 

void SubclassWindowFunction(); 

Installs the instance thunk as the WindowProc and saves the old window function in 
DefaultProc. 


See also TWindow::DefaultProc, TWindow::DefaultProcessing 


Transfer 

virtual uint Transfer(void* buffer, TTransferDirection direction); 

Transfers data to or from any window with or without children and returns the total 
size of the data transferred. Transfer is a general mechanism for data transfer that can be 
used with or without using TransferData. The direction supplied specifies whether data is 
to be read from or written to the supplied buffer, or whether the size of the transfer data 
is simply to be returned. Data is not transferred to or from any child windows whose 
wfTransfer flag is not set. The return value is the size (in bTransferData). 


virtual void TransferData(TTransferDirection direction); 

A window usually calls on TransferData during setup and closing of windows and relies 
on the constructor to set TransferBuffer to something meaningful. TransferData calls the 
Transfer member function of each participating child window, passing a pointer to 
TransferBuffer as well as the direction specified in direction (tdSetData, tdGetData, or 
tdSizeData). 


Seealso TWindow::EnableTransfer, TWindow::DisableTransfer, 
TWindow::SetupWindow, TWindow::TransferBuffer 


UnregisterHotKey 
bool UnregisterHotKey(int idHotKey); 
UnregisterHotKey unregisters a hotkey ID with a current application. 


Seealso TWindow::RegisterHotKey 


UpdateWindow 
void UpdateWindow(); 


UpdateWindow updates the client area of the specified window by immediately sending 
a WM_PAINT message. 


Validate 

void Validate(); 

Calls the function ValidateRect to validate (that is, remove from the area to be uae) 
the entire client area (the area you can use for drawing). 


Seealso TWindow::InValidate | 


ValidateRect 
void ValidateRect(const TRect& rect); 
ValidateRect validates a portion of the client area indicated by rect. 
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ValidateRgn 

void ValidateRgn(HRGN hRgn); 

ValidateRgn validates the client area within a region of the current window. hRgn is a 
handle to the client area that's to be removed from the region to be updated. If hRgn is 
NULL, the entire client area is removed from the region to be updated. 


Seealso TWindow::InvalidateRgn 


WindowFromPoint 
static HWND WindowFromPoint(const TPoint& point) const; 
Returns the handle of the window in which the specified point (point) lies. 


Seealso —TWindow::ChildWindowFromPoint 


WindowProc 

virtual LRESULT WindowProc(uint msg, WRARAM wParam, LPARAM I|Param); 

WindowProc processes incoming messages by calling EvCommand to handle 
WM_COMMAND messages, EvCommandEnable to handle WM_COMMAND_ENABLE 
messages, and dispatching for all other messages. 


See also TWindow::DefWindowProc 


WinHelp 

bool WinHelp(const char far* helpFile, uint command, uint32 data); 

WinHelp invokes a specified help system. helpFile points to a string containing the 
directory path and name of the help file. command, which indicates the type of help 
requested, can be one of the Windows Help_xxxx constants such as HELP_CONTEXT, 
HELP_HELPONHELP, HELP_INDEX, HELP_MULTIKEY, H™'LP_QUIT, or 
HELP_SETINDEX. data contains keywords that indicate the help topic items. For 
example, in the sample ObjectWindows file, HELP.CPP, WinHelp is called with the 
arguments HELP_CONTEXT and HELP_MENUITEMA if the F7 key is pressed. 


void TOwlHelpWnd: :CmMenultemA ( } 
{ 
if (FiPressed) { 
WinHelp (HelpFile, HELP CONTEXT, HELP _MENUITEMA) ; 
FiPressed = false; 
} else { 
MessageBox("In Menu Item A command", Title, MB ICONINFORMATION) ; 
} 
} 


You can also include bitmaps in your Help file by referencing their file names or by 
copying them from the Clipboard. For more information about how to create Help files, 
see the online Help documentation. 


Protected data members 


BkgndColor 
uint82 BkgndColor; 
Stores the current background color set by the TWindow::SetBkgndColor function. 


Seealso TWindow::SetBkgndColor 
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CursorModule 
TModule* CursorModule; 

_ Holds the module ID for the specified cursor. A value of 0 indicates a standard system 
cursor. 


See also aT Window:sCucserResid 


CursorResld 

TResld CursorResld; 

Holds the cursor resource ID for the window's cursor. If the data member, Supsciioalie 
is 0, CursorResId could be one of the following IDC_Xxxx constants that represent 
different kinds of cursors: 


IDC_ARRO Customary arrow cursor 

IDC_CROSS Crosshair cursor 

IDC_IBEAM I-beam cursor 

IDC_ICON Unfilled icon cursor 

IDC_SIZE A smaller square in the right inside corner of a larger square 
IDC_SIZENESW Dual-pointing cursor with arrows pointing southwest and northeast 
IDC_SIZENS Dual-pointing cursor with arrows pointing south and north 
IDC_SIZENWSE Dual-pointing cursor with arrows pointing southeast and northwest 
IDC_SIZEWE Dual-pointing cursor with arrows pointing east and west 
IDC_UPARROW Vertical arrow cursor | 7 | 

IDC_WAIT Hourglass cursor 


See also TWindow::SetCursor 


hAccel 
HACCEL hAccel: 
Holds the handle to the current Windows accelerator table associated with this window. 


HCursor , 

HCURSOR HCursor; 

Holds a handle to the window's cursor. The cursor is retrieved using CursorModule and 
CursorResId and set using SetCursor. 


TransferBuffer 

void* TransferBuffer; 

TransferBuffer points to a buffer to be used in transferring data in and out of the 
TWindow. A TWindow assumes that the buffer contains data used by the mneoNs) in its 
child list. If 0, no data is to be transferred. 


Seealso tdxxxx constants 


Protected constructor 


Constructor 
TWindow(); 
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Constructor used with virtually derived classes. Immediate derived classes must call 
Init before the construction of the object is finished. 


Protected member functions 


CleanupWindow 

virtual void CleanupWindow(); 

Always called immediately before the HWindow becomes invalid, CleanupWindow 
gives derived classes an opportunity to clean up HWND related resources. This 
function is the complement to SetupWindow. 


Override this function in your derived class to handle window cleanup. CleanupWindow 
gives derived classes a chance to clean up hwnd-related resources. Derived classes 
should call the base class's version of CleanupWindow as the last step before returning. 
The following example from the sample program, appwin.cpp, illustrates this process: 


//Tell windows that we are not accepting drag and drop transactions any more and perform 
other window cleanup. 
void 
TAppWindow: :CleanupWindow ( ) 
{ 
AppLauncherCleanup(); 
DragAcceptFiles (false) ; 
TWindow: :CleanupWindow/(); 


} 
~Seealso TWindow::SetupWindow 


DispatchScroll | 
void DispatchScroll(uint scrollCode, uint thumbPos, HWND hWndCtrl); 
Called by EvHScroll and EvVScroll to dispatch messages from scroll bars. 


GetClassName 

virtual char far* GetClassName(); 

Returns the Windows registration class name. The default class name is generated using 
the module name plus "Window." If you are registering a new class or changing the 
name of an existing window class, override this function in your derived class. 


Seealso TWindow::GetWindowClass, WNDCLASS struct 


GetWindowClass 

virtual void GetWindowClass(WNDCLASS& wndClass); 

Redefined by derived classes, GetWindowClass fills the supplied MS-Windows 
registration class structure with registration attributes, thus, allowing instances of 
TWindow to be registered. This function, along with GetClassName, allows Windows 
classes to be used for the specified ObjectWindows class and its derivatives. It sets the 
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fields of the passed WNDCLASS parameter to the default attributes appropriate for a 
TWindow. The fields and their default attributes for the class are the following: 


cbClsExtra 
cbWnd Extra 


hInstance 
hIcon 


hCursor 


hbrBackeground . 


lpszMenuName 


lpszClassName 
lpfnWndProc 


style 


0 (the number of extra bytes to reserve after the Window class structure). This value is 


not used by ObjectWindows. 


0 (the number of extra bytes to reserve after the Window instance). This value i is not 
used by ObjectWindows. 


The instance of the class in which the window procedure exists 


0 (Provides a handle to the class resource.) By default, the application must create an 
icon if the application's window is minimized. 


IDC_ARROW (provides a handle to a cursor resource) 
COLOR_WINDOW + 1 (the system background color) 


0 (Points to a string that contains the name of the class's menu.) By default, the 
windows in this class have no assigned menus. 


Points to a string that contains the name of the window class. 
The address of the window procedure. This value is not used by ObjectWindows. 
CS_DBLCLKS 


The style field can contain one or more of the following values: 


CS_BYTEALIGNCLIENT 


CS_BYTEALIGNWINDOW 


CS_CLASSDC 


CS_DBLCLKS 


CS_GLOBALCLASS 


CS_HREDRAW 


CS_NOCLOSE 
CS_OWNDC 
CS_PARENTDC 
CS _SAVEBITS 


CS_VREDRAW 


Aligns the window's client on a byte boundary in the x direction. This 
alignment, designed to improve performance, determines the width and 
horizontal position of the window. 


Aligns a window ona byte boundary in the x direction. This alignment, 
designed to improve performance, determines the width and horizontal 
position of the window. 


Allocates a single device context (DC) that's going to be shared by all of the 
window in the class. This style controls how multi-threaded applications 
that have windows belonging to the same class share the same DC. 


Sends a double-click mouse message to the window procedure when the 
mouse is double-clicked on a window belonging to this class. 


Allows an application to create a window class regardless of the instance 
parameter. You can also create a global class by writing a DLL that 
contains the window class. 


If the size of the window changes as a result of some movement or 
resizing, redraws the entire window. 


Disables the Close option on this window's system menu. 
Enables each window in the class to have a different DC. 
Passes the parent window's DC to the child windows. 


Saves the section of the screen as a bitmap if the screen is covered by 
another window. This bitmap is later used to recreate the window when it 
is no longer obscured by another window. 


If the height of the client area is changed, redraws the entire window. 
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After the Windows class structure has been filled with default values by the base class, 
you can override this function to change the values of the Windows class structure. For 
example, you might want to change the window's colors or the cursor displayed. 


Seealso TWindow::GetClassName, WNDCLASS struct 


Init 

void Init(TWindow* parent, const char far* title, TModule* module); 

Allows for further initialization after default construction of a window in virtually 
derived classes. 


LoadAcceleratorTable 

void LoadAcceleratorTable(); 

Loads a handle to the window's accelerator table specified in TWindowsAttr structure 
(Attr.AccelTable). If the accelerator does not exist, LoadAcceleratorTable produces an 
"Unable to load accelerator table" diagnostic message. 


Seealso TWindowAttr structure 


RemoveChild 

void RemoveChild(TWindow* child); 

Removes a child window. This family of ObjectWindows TWindow functions uses the 
ObjectWindows list of objects rather the Window's HWND list. 


Seealso TWindow::GetFirstChild, TWindow::GetLastChild, TWindow::Next, 
TWindow::Previous 


SetupWindow 

virtual void SetupWindow(); 

SetupWindow is the first virtual function called when the HWindow becomes valid. 
TWindow’s implementation performs window setup by iterating through the child list, 
attempting to create an associated interface element for each child window object for 
whom autocreation is enabled. (By default, autocreation is enabled for windows and 
controls, and disabled for dialog boxes.) SetupWindow then calls TransferData. 


SetupWindow can be redefined in derived classes to perform additional special 
initialization. Note that the HWindow is valid when the overridden SetupWindow is 
called and that the children's HWindows are valid after calling the base classes' 
SetupWindow function. 


The following example from the sample program, appwin.cpp, illustrates the use of an 
overridden SetupWindow to setup a window, initialize .INI entries, and tell Windows 
that we want to accept drag and drop transactions. 


void TAppWindow: :SetupWindow ( ) 


{ 
TFloatingFrame: :SetupWindow(); 


InitEntries();  // Initialize .INI entries. 
RestoreFromINIFile(); // from Applaunc.ini in the startup directory 
UpdateAppButtons (); 


DragAcceptFiles (true) ; 
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Seealso [FrameWindow: ‘SetupWindow, TComboBox::SetupWindow, — 
TWindow::CleanupWindow 


Response table entries 


EV_WM_CREATE EvCreate 
~EV_WM_CLOSE EvClose 
EV_WM_DESTROY EvDestroy — 
EV_WM SIZE EvSize 
EV_WM_MOVE EvMove 
EV_WM_NCDESTROY EvNcDestroy 
EV_WM_QUERYENDSESSION EvQueryEndSession 
EV_WM_COMPAREITEM EvCompareltem 
EV_WM_DELETEITEM EvDeleteItem 
EV_WM_DRAWITEM EvDrawltem 
EV_WM_MEASUREITEM EvMeasureltem 
EV_WM_CHILDINVALID EvChildInvalid 
-EV_WM_VSCROLL | EvVScroll 
EV_WM_HSCROLL EvHScroll 
EV_WM_PAINT EvPaint 
EV_WM_SETCURSOR EvSetCursor 
EV_WM_LBUTTONDOWN EvLButtonDown 
EV_COMMAND(CM_EXIT, CmExit) CmExit 
EV_WM_SYSCOLORCHANGE EvSysColorChange 
EV_WM_KILLFOCUS EvKillFocus 
EV_WM_ERASEBKGND | EvEraseBkgnd 
EV_MESSAGE(WM_CTLCOLORMSGBOXx, EvWin32CtlColor) : EvWin32CtlColor’ 
EV_MESSAGE(WM_CTLCOLOREDIT, EvWin32CtlColor) EvWin32CtiColor! 
EV_MESSAGE(WM_CTLCOLORLISTBOX, EvWin32CtlColor) EvWin32CtiColor! 
EV_MESSAGE(WM_CTLCOLORBTN, EvWin32CtlColor) EvWin32CtlColor! 
EV_MESSAGE(WM_CTLCOLORDLAG, EvWin32CtlColor) EvWin32CtiColor! 
EV_MESSAGE(WM_CTLCOLORSCROLLBAR, EvWin32CtlColor) EvWin32CtColor! 
EV_MESSAGE(WM_CTLCOLORSTATIC, EvWin32CtlColor) EvWin32CtIColor! 


1. These response table entries are used only under the Win32 API. 


Holds TWindow attributes set during construction of a window. Your program controls 
a window's creation by passing these values to one of TWindow's creation routines. If the 
window is streamed, these attributes are also used for re-creation. 
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Public data members 


AccelTable 
TResID AccelTable; 
Holds the resource ID for the window's accelerator table. 


Seealso TApplication::HAccTable, TWindow::LoadAcceleratorTable 


ExStyle 

uint32 ExStyle; 

Contains the extended style values of your window. These can be any one of the 
extended style constants (WS_EX_DLGMODALFRAME, 
WS_EX_NOPARENTNOTIPY, WS_EX_TOPMOST, WS_EX_SHADOW). See 
TWindow::AdjustWindowRectEx for a description of these constants. 


Seealso TWindow::AdjustWindowRectEx 


Id 

int Id; 

Contains the identifier of the child window. For a dialog box control, Id is its resource 
identifier. If Win32 is defined, Id is set to GetWindowLong; otherwise Id is set to 
GetWindowWord. 


Menu 

TResld Menu; 

Contains the resource ID for the menu associated with this window. If no menu exists, 
Menu is 0. 


Param 

char far* Param; 

Contains a value that is passed to Windows nen the window is created. This value 
identifies a data block that is then available in the message response functions associated 
with WM_CREATE. Param is used by TMDIClient and can be useful when converting 
non-ObjectWindows code. 


Style 

uint32 Style; 

Contains the values that define the style, shape, and size of your window. Although 
TWindow sets Attr.Style to WS_CHILD and WS_VISIBLE, you can also use other 
combinations of the following style constants: 


‘Value Se ee ts 

. Ws_ BORDER | _ Creates a window witha thin lined border 

WS_CAPTION Creates a window with a title bar. 

Ws_CHILD Creates a child windows. Cannot be used with popup styles. 

WS_CHILDWINDOW Creates a child window. - 

WS_CLIPCHILDREN Used when creating a parent window. Excludes the area occupied by 
child windows when drawing takes place within the parent window. 

WS_CLIPSIBLINGS Clips child windows relative to ne child window that receives a paint 
message. 
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WS_DLGFRAME 
WS_GROUP 


WS_HSCROLL 
WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS_MINIMIZE 
WS_MINIMIZEBOX 
WS_OVERLAPPED 
WS_OVERLAPPEDWINDOW 


WS_POPUP 
WS_POPUPWINDOW 


WS_SYSMENU 


WS_TABSTOP 
Ws_THICKFRAME 
Ws_VISIBLE 
WS_VSCROLL 


See also 


X, Y, W, H 
int X, Y, W, H; 


reates a window that cannot receive user input. 
Creates a window having a typical dialog box style (without a title bar). 


Indicates the first control in a group of controls, which the user can. 
change by pressing the direction keys. 


Window has a horizontal scroll bar. 
Window is initially maximized. 


Window has a maximize button. 


Window is initially minimized. 
Window has a minimize button. 
Creates an overlapped window with a title bar and a border. 


Overlapped window has the WS_LOVERLAPPED, WS_CAPTION, 
WS_SYSMENU, WS_THICKFRAME, WS _ MINIMIZEBOX, and 
WS_MAXIMIZEBOXxX styles. 


Creates a popup window. Cannot be used with child window sive. 


Creates a popup window with WS_BORDER, WS_POPUP, and 
WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW 
styles combine to create a system menu. 


Window has a system menu box in its title bar. Must also indicate the 
WS_CAPTION style. 


Control can receive the keyboard focus when TAB key is pressed. 
Window has a border that lets you change the window size. 
Window is initially visible. | 

Window has a vertical scroll bar. 


TWindow: ‘-IsWindow Visible | 


Xand _Y contain the screen coordinates of the top left corner of the window. W and H 
contain the width and height values of the window. 


TWindowFlag enum 


window.h 


TWindowFlag enum 
enum TWindowFlag { 


wiAlias, wfAutoCreate, wiFromResource, wfShrinkToClient, wiMainWindow, wiFullyCreated, wfStreamTop, | 
wiPredefinedClass, wfTransfer, wfUnHidden, wfUnDisabled, 


}; 


Define bit masks for the internally used flag attributes of TWindow. A wfXxxx mask is 
defined for each of these attributes: 


Table 2.11 


TWindow attribute masks 


wfAlias 
wfAutoCreate 
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Constant — Meaning feet nn en 
| wfFullyCreated | Window is fully created and not being destroyed. 
wfFromResource HWindow comes from an HWND created from a resource definition. 
wfMainWindow Window is a main window. 
wfPredefinedClass The window belongs to a predefined Window's not an ObjectWindows class. 
wfShrinkToClient Tells a frame window to shrink itself to fit around the client window. 
wfStreamTop Indicates the topmost window of the collection of windows to be streamed. 
wfTransfer Participates in the Transfer mechanism. 
wfUnDisabled Temporarily used when an MDI child window is destroyed. 
wfUnHidden Temporarily used when an MDI child window is destroyed. 


Seealso TWindow::CreateChildren, TWindow::EnableAutoCreate 


Derived from TDC, TWindowDC is a DC class that provides access to the entire area 
owned by a window. This is the base class for any DC class that releases its handle when 
it is finished. 


See also 
TWindowDC::Wnd 


Public constructor and destructor 


Constructor 

TWindowDC(HWND wnd); 

Creates a TWindow object with the given owned window. The data member Wnd is set 
to wnd. 


Destructor 
~TWindowDC(); 
Destroys this object. 


Protected constructor 
Constructor 


TWindowDC(); 
Used for derived classes only. 


Protected data member 
Wnd | 


HWND Wnhd; | 
Holds a handle to the window owned by this DC. 
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See also TWindowDc: -TWindowDC 


TWindowView class Oe docview.h 


Derived from both TWindow and TView, TWindowView is a streamable base class that 
can be used for deriving window-based views. TWindowView's functions override 
TView's virtual function to provide their own implementation. By deriving a window- 
view class from TWindow and TView, you add window functionality to the view of your 
document. 


Public constructor and destructor 


Constructor 

TWindowView (TDocument& doc, TWindow* parent = 0); 

Constructs a TWindowView interface object associated with the window view. Sets 
Viewld to NextViewld. Calls the associated document's AttachView to attach the view to 
the document. | 


Destructor 

~TWindowView(); | 

Destroys a TWindowView object and calls the associated document's Detach View function 
to detach the view from the associated document. 


Public member functions 


CanClose 

bool CanClose(); 

Overrides TView::CanClose and returns nonzero if the window can be closed. Checks all 
~ of the associated document's CanClose functions. These must return nonzero before the 

window view can be closed. © | 


~Seealso TWindow::CanClose 


GetViewName 
const char far* GetViewName(); 
Overrides TView::GetViewName and returns StaticName, the name of the view. 


Seealso TView::GetViewName 


GetWindow 
TWindow* GetWindow() 
Overrides TView::GetWindow and returns the TWindowView object as a TWindow. 


Seealso TEditView::GetWindow, TView::GetWindow 


SetDocTitle 
bool SetDocTitle(const char far* docname, int index) 
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Overrides T’View::SetDocTitle and stores the document title. This name is forwarded up 
the parent chain until a TFrameWindow object accepts the data and displays it in its 
caption. 


Seealso TView::SetDocTitle, TWindow::SetDocTitle 
StaticName 
static const char far* StaticName(); 


Returns "Window View," the descriptive name of the view. This title is displayed in the 
user-interface box. 


Response table entries 


Response table entry Member function : 
EV_VN_ISWINDOW VulsWindow 


TWindow::TXWindow class window.h 


Form 1 


Form 2 


A nested class, TXWIndow describes an exception that results from trying to create an 
invalid window. 


Public constructors 


Constructors 
TXWindow(TWindow* win = 0, uint resourceld = IDS_INVALIDWINDOW); 
Constructs a TXWindow object with a default resource ID of IDS_INVALIDWINDOW. 


TXWindow(const TXWindowé src); 
Constructs a TXWindow object with the window that failed. 


Public data members 


Window 
TWindow* Window; 
Points to the window object that is associated with the exception. 


Public member functions 


Clone 

TXOwl* Clone(); 

Makes a copy of the exception object. Clone() must be implemented in any class derived 
from TXOuwl. 


Seealso TXOwl 
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Msg 
Static string Msg(TWindow’*, uint resourceid); 
Converts the resource ID to a string and returns the string message. 


Throw 

void Throw(); 

Throws the exception object. Throw() must be implemented in any class derived from 
TXOwl. 


Seealso TXOwl 


Unhandled | 

int Unhandled(TModule* app, unsigned promptResid); 

Called if an exception caught in the window's message loop has not been handled. 
Unhandled() deletes the window. This type of exception can occur if a window cannot be 
created. 7 


Form 1 


Form 2 


Describes an exception that results from setting TModule::Status to nonzero. This 
exception is included for backward compatibility with ObjectWindows 1.0. 


Public constructors 


Constructors 
TXCompatibility(int statusCode); 
Constructs a TXCompatibility object. 


TXCompatibility(const TXCompatibility& src); 
Constructs a TXCompatibility object with the window that failed. 


Public member functions 


Clone 

TXOwl Clone(); 

Makes a copy of the is object. Clone must be implemented in any class derived 
from TXOuwl. ? 


MapStatusCodeToString 
Static string MapStatusCodeToString(int statusCode); 
Retrieves Tmodule’s status code and coverts it to a string. 


Throw 

void Throw(); 

Throws the exception object. Throw must be implemented in any class derived from 
TXOuwl. 
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Unhandled 

int Unhandled(TModule* app, unsigned promptResld); 

If an exception caught in the message loop has not been handled, Unhandled is called. 
Unhandled deletes the window. This type of exception could occur if a window can't be 
created. 


TMenu::TXMenu class menu.h 


A nested class, TXMenu describes an exception that occurs when a menu item cannot be 
constructed. | 


Public constructors 


Constructors 
TXMenu(unsigned resid = IDS_GDIFAILURE); 
Constructs a TXMenu exception object with a default IDS_GDIFAILURE message. 


Public member functions 


Clone 
TXOwl Clone(); 
Makes a copy of the exception object. 


Throw 
void Throw(); 
Throws a T’XMenu exception. 


Describes an exception that results from running out of memory. 


Public constructors 


Constructors 
TXOutOfMemory(); 
Constructs a TXOutOfMemory object. 


Public member functions 


Clone 

TXOwl Clone(); 

Makes a copy of the exception object. Clone must be implemented in any class derived 
from TXOwl. 
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Throw 
void Throw(); | 
Throws the exception object. Throw must be implemented in any class derived from 
TXOul. 
TXQwl class | except.h 


TXOuwl is a a parent class for several classes designed to describe exceptions, that is, 
abnormal conditions outside the program's control. In most cases, you will derive a new 
class from TXOuwl instead of using this one directly. The ObjectWindows classes derived 
from TXOuw! include | 


TX Compatibility—Describes an exception that occurs if TModule::Status is not zero. 


TValidator::TXValidator—Describes an exception that occurs if there is an invalid 
validator expression. 


TWindow::X Window—Describes an exception that results from aying to create an 
invalid window. 


TGdiObject::TXGdi—Describes an exception that results from creating an invalid GDI | 
object. | 


TApplication::TXInvalidMainWindow—Describes an exception that results from 
creating an invalid main window. 


TMenu::XMenu—Describes an exception that occurs when a menu object is invalid. 


TModule::XInvalidModule—Describes an exception that occurs if a TModule object is 
invalid. | 


TPrinter::TXPrinter—Describes an exception that occurs if a printer DC is invalid. 


TX OutOfMemory—Describes an exception that occurs if an out of memory error 
occurs. | 


Each of the exception classes describes a particular type of exception. When your 
program encounters a given situation that's likely to produce this exception, it passes 
control to the specified exception-handling object. If you use exceptions in your code, 
you can avoid having to scatter error-handling procedures throughout your program. 


To create an exception handler, place the keyword try before the block of code that 
might produce the abnormal condition (the code that might generate an exception 
object) and the keyword catch before the block of code that follows the try block. If an 
exception is thrown within the try block, the classes within each of the subsequent catch 
clauses are checked in sequence. The first one that matches the class of the exception 
object is executed. 


The following example from MDIFILE.CPP, a sample program on your distribution — 
disk, shows how to set up a try/catch block around the code that might throw an 
exception. 


void TMDIFileApp: :CmRestoreState( ) 
{ 
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Form 1 


Form 2 


char* errorMsg = 0; 
ifpstream is(DskFile) ; 
1f (is.bad({)) 


TXOwl class 


errorMsg = “Unable to open desktop file."; 


/ 


— 


try block of code // 
else { 


if (Client->CloseChildrenParen) { 


try { 
ig >>* this; 
if (is.bad()) 


errorMsg = "Error reading desktop file."; 


else 


Client->CreateChildren|(); 


} 
// catch block of code // 
catch (xalloc) { 
Client->CloseChildren(); 


errorMsg = "Not enough memory to open file."; 


} 
} 
} 


if (errorMsg) 


MainWindow->MessageBox{(errorMsg, "Error", 


MB_OK | MB_ICONEXCLAMATION) ; 


} 


See also 
TXBase 


Constructors 


Public constructors and destructor 


TXOwl(const string& msg, unsigned resld = 0); 
Constructs a TXOw! object with a string message (msg). 


TXOwl(unsigned resid, TModule* module = ::module); 


Loads the string resource identified by the resId parameter and uses this resource to 


initialize the TXBase object. 


Destructor 
~TXOwl(); 
Destroys a TXOw! object. 


Public data member 


Resid 
unsigned Resld; 


Resource ID for a TXOwl object. 
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VNXXXX view notification constants 


Public member functions 


Clone 
TXOwl* Clone(); 


Makes a copy of the exception object. Clone must be overridden in any class derived 
from TXOwl. 


GetErrorCode 
unsigned GetErrorCode () const; 
Returns the resource ID. 


ResourceldToString 

static string ResourceldToString(bool* found, unsigned resid, TModule* module = module); 

Converts the resource ID to a string and returns a string that identifies the exception. If 
the string message cannot be loaded, returns a "not found" message. Sets the found 
parameter to TRUE if the resource is located; otherwise, sets found to FALSE. 


Throw 

void Throw(); 

Throws the exception object. Throw must be implemented in any class derived from 
TXOuwl. 


Unhandled 

virtual int Unhandled(TModule* app, sions promptResld): 

Unhandled is called when an unhandled exception is caught at the main message loop 
level. 


VNxxxx view notification constants docview.h 


The view notification constants are used to notify the view of a given event. 


vnCommit Changes are committed to the document. 

vnCustomBase Base event for document notifications. 

vnDocOpened Document has been opened. 

vnDocClosed Document has been closed. 

vilsDirty Is true if uncommitted changes are present. 

vninvalidate Is true if uncommitted changes are present. 

vnisWindow Is true if the HWND passed belongs to this view. 

vnRevert Document's previous data is reloaded and overwrites the view's current data. 


vnViewOpened =A new view has been constructed. 
vnViewClosed — A view is about to be destroyed. 


Seealso TListView, TEditView 
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ObjectWindows event handlers 


These topics include several tables that list predefined ObjectWindows response-table 
macros and event-handling functions. Each table lists the name of the ObjectWindows 
macro, any required macro arguments, and the associated event-handling function. 


These button macros handle BN_xxxx notification codes. To determine the name of the 
notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix. 


Table 3.1 Button notification messages 


EV_BN_CLICKED ID, UserName “void UserName() 
EV_BN_DISABLE ID, UserName void UserName ) 
EV_BN_DOUBLECLICKED ID, UserName vold UserName ( ) 
EV_BN_HILITE ID, UserName void UserName | ) 
EV_BN_PAINT ID, UserName void UserName ( ) 
EV_BN_UNH:LITE ID, UserName void UserName ) 


The following macros handle messages that a child window sends to its parent: 


Table 3.2 Child ID notification messages 


void UserName (WPARAM) 
void UserName (UINT) 
Code, UserName void UserName 

ID, Code, UserNam void UserName 


EV_CHILD_NOTIFY_AND_CODE _ ID, Code, UserName 
EV_CHILD NOTIFY_ALL CODES _ ID, UserName 
EV_NOTIFY_AT_CHILD 
EV_CHILD_ NOTIFY 
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These combo box macros handle CBN_xxxx notification codes. To determine the name 
of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix. 


Table 3.3 Combo box notification messages 


ID, UserName 


void UserName | 


EV_CBN_DBLCLK ID, UserName void UserName |) 
EV_CBN_ DROPDOWN ID, UserName void UserName | ) 
EV_CBN_EDITCHANGE ID, UserName void UserName ( ) 
EV_CBN_EDITUPDATE _ ID, UserName void UserName () 
~ EV_CBN_ERRSPACE ID, UserName | void UserName () 
_ EV_CBN_KILLFOCUS ID, UserName void UserName( ) 
EV_CBN_SELCHANGE ID, UserName void UserName |) 
EV_CBN_SELENDCANCEL __ ID, UserName void UserName ( ) 
EV_CBN_SELENDOK ID, UserName void UserName( ) 
EV_CBN_SETFOCUS ID, UserName void UserName ( ) 


These macros handle WM_COMMAND messages: 


Table 3.4 | Command messages 


EV_COMMAND 
EV_COMMAND_AND_ID CMD ID, UserName 
EV_COMMAND_ENABLE CMD ID, UserName 


CMD ID, UserName 


void UserName ( ) 
void UserName (WPARAM) 
void UserName (TCommandEnabler&) 


These macros handle messages generated by the document manager: 


Table 3.5 Document manager messages 


EV_OWLDOCUMENT ID, UserName void UserName(TDocument& document) 
EV_OWLNOTIFY ID, UserName bool UserName (LPARAM) 
EV_OWLVIEW Bee ae void UserName (TView& view) 


These macros handle view-related messages generated by the document manager. 
VnHandler is a generic term for the view notification handler function. 


Table 3.6 © Document view messages 


—ViIN_ p 
EV_VN_VIEWCLOSED bool VnViewClosed (TView* view) 
EV_VN_DOCOPENED 
EV_VN_DOCCLOSED 
EV_VN_COMMIT | 


EV_VN_REVERT 


bool VnDocOpened(int openMode) 
bool VnDocClosed(int openMode) 
bool VnCommit (bool force) 


bool VnRevert (bool clear) 
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Table 3.6 © Document view messages (continued) 


EV_VN_ISDIRTY 
EV_VN_ISWINDOW 


These edit control macros handle EN_xxxx notification codes. To determine the name of 
the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix. 


bool ValsDirty (} 
bool VnIsWindow(HWND hwnd) 


Table 3.7 —_ Edit control notification messages 


Macro 

EV_EN_ CHANGE 
EV_EN_ERRSPACE 
EV_EN_HSCROLL 
EV_EN_KILLFOCUS 
EV_EN MAXTEXT 
EV_EN_SETFOCUS 
EV_EN_UPDATE 
EV_EN_VSCROLL 


Macroarguments =—s&3Reesponse function declaration 


ID, UserName 
ID, UserName 
ID, UserName 
ID, UserName 
ID, UserName 
ID, UserName 
ID, UserName 
ID, UserName 


These list box macros handle LBN_xxxx notification codes. To determine the name of 
the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix. 


Table 3.8 —_List box notification messages 


EV_LBN DBLCLK — 
EV_LBN_ERRSPACE 
EV_LBN_KILLFOCUS 
EV_LBN_SELCANCEL 


“ID, UserName 


ID, UserName 
ID, UserName 
ID, UserName 


void UserName 
void UserName 
void UserName 


void UserName 


void UserName 


() 
() 
() 
() 
void UserName ( ) 
() 
void UserName ( ) 

() 


void UserName 


void UserName 
void UserName 


void UserName 


void UserName 


EV_LBN_SELCHANGE ID, UserName 
EV_LBN_SETFOCUS ID, UserName void UserName 


) 
) 
) 
) 


( 
( 
( 
void UserName ( 
( 
( 


These macros handle ObjectComponents messages. 


Table 3.9 | ObjectComponents messages 


EV_OC_VIEWPARTINVALID pool EvOcViewPartInvalid(TOcPart faré) 
EV_OC_ VIEWTITLE const char far* EvOcViewTitle() | 
EV_OC_VIEWBORDERSPACEREQO bool EvOcViewBorderSpaceReg(TRect far* rect) 
EV_OC_VIEWBORDERSPACESET bool EvOcViewBorderSpaceSet (TRect far&) 
EV_OC_VIEWDROP | bool EvOcViewDrop (TOcDragDrop faré) 
EV_OC_VIEWDRAG | bool EvOcViewDrag(TOcDragDrop fark) 
EV_OC_VIEWSCROLL bool EvOcViewScroll (TOcScrollDir) 
EV_OC_VIEWGETSCALE bool EvOcViewGetScale(TOcScaleFactor&) 
EV_OC. VIEWGETSITERECT bool EvOcViewGetSiteRect (TRect far* ) 
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EV_OC_VIEWPAINT 
EV_OC_VIEWSAVEPART 
EV_OC_VIEWLOADPART 
EV_OC_VIEWINSMENUS 
EV_OC_VIEWSHOWTOOLS, 
EV_OC_VIEWGETPALETTE 
EV_OC_VIEWCLIPDATA, 
EV_OC_VIEWCLOSE 
EV_OC_VIEWPARTSIZE 
EV_OC_VIEWOPENDOC 
EV_OC_VIEWATTACHWINDOW 
EV_OC_VIEWSETSCALE 
EV_OC_APPINSMENUS 
EV_OC_APPMENUS 
EV_OC_APPPROCESSMSG 
EV_OC_APPFRAMERECT 
EV_OC_APPBORDERSPACEREQ 
EV_OC_APPBORDERSPACESET 
EV_OC_APPSTATUSTEXT 
EV_OC_APPRESTOREUI 
EV_OC_APPDIALOGHELP 
EV_OC_APPSHUTDOWN 


| bool 


bool EvOcViewPaint (TOcViewPaint far&) 


bool EvOcViewSavePart (TOcSaveLoad far& ocSave) 
bool EvOcViewLoadPart (TOcSaveLoad far& ocLoad) 
bool EvOcViewInsMenus (TOcMenuDescr far&) 

bool EvOcViewShowTools(TOcToolBarInfo far& tbi) 
bool EvOcViewGetPalette (LOGPALETTE far* far*) 
HANDLE EvOcViewClipData(TOcFormat far&) 

bool 
bool 
bool 
bool 
bool 
bool 
bool 
bool 
bool 
bool 


EvOcViewClose () 
EvOcViewPartSize(TRect far&) 
EvOcViewOpenDoc(const char far&) 
EvOcViewAttachWindow( ) 
EvOcViewSetScale(TOcScaleFactor&) 
EvOcAppInsMenus (TOcMenuDescr far&) 
EvOcAppMenus (TOcMenuDescr far&) 
EvOcAppProcessMsg (MSG far*) 
EvOcAppFrameRect (TRect far*) 
EvOcAppBorderSpaceReq(TRect far*) 
EvOcAppBorderSpaceSet (TRect far*) 
void EvOcAppStatusText (const char far*) 
void EvOcAppRestoreUl ( ) 

void EvOcAppDialogHelp (T0cDialogHelp far& dh) 
void EvOcAppShutDown ( ) 


The following scrollbar control macros handle SB_xxxx notification codes. To determine 
the name of the notification code that corresponds to the EV_XXXX macro, remove the 


EV_ prefix. 


Table 3.10 Scroll bar notification messages 


EV_SB_LINEDOWN ID, UserName 
EV_SB_LINEUP ID, UserName 
EV_SB_PAGEDOWN ID UserName 
EV_SB_PAGEUP _ID, UserName 
EV_SB_TOP ID, UserName 
EV_SB_BOTTOM ID, UserName 
EV_SB_THUMBPOSITION ID, UserName 
EV_SB_ENDSCROLL ID, UserName 

ID, UserName 


EV_SB_BEGINTRACK 


void UserName 


void UserName 
void UserName 
void UserName 
void UserName 
void UserName 
void UserName 
void UserName 


() 
() 
() 
() 
() 
() 
() 
() 
() 


void UserName 


These macros handle Windows messages. These macros are defined in windowev.h. To 
| determine the name of the Windows message that corresponds to the EV_XXXX macro, 
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remove the EV_ prefix. For example, WM_ACTIVATE is the name of the Windows 
message that the EV_WM_ACTIVATE macro handles. These macros, which crack the 
standard Windows messages (break the LPARAM and WPARAM parameters into 
separate parts), take no arguments. They pass the cracked parameters directly to the 
predefined EVxxxx message function. The standard Windows messages are described 
in your Windows documentation. 


Table 3.11 Standard Windows messages 


Macro 
EV_ WM _ACTIVATE 
EV_WM_ACTIVATEAPP 


EV_WM_ACTIVATEAPP 


EV_WM_ASKCBFORMATNAME 


EV_WM_CANCELMODE 
EV_WM_CHANGECBCHAIN 
EV_WM_CHAR 
EV_WM_CHARTOITEM 
EV_WM_CHILDACTIVATE 
EV_WM_CHILDINVALID 
EV_WM_CLOSE 
EV_WM_COMPACTING 
EV_WM_COMPAREITEM 


EV_WM_CREATE 
EV_WM_CTLCOLOR 
EV_WM_DEADCHAR 
EV_WM_DELETEITEM 


EV_WM_DESTROY 

EV_WM "DESTROYCLIPBOARD 
EV_WM_DEVMODECHANGE 
EV_WM_DRAWCLIPBOARD 
EV_WM_DRAWITEM 
EV_WM_DROPFILES 
EV_WM_ENABLE 
EV_WM_ENDSESSION 
EV_WM_ENTERIDLE 
EV_WM_ERASEBKGND 
EV_WM_FONTCHANGE 
EV_WM_GETDLGCODE 
EV_WM_GETFONT 
EV_WM_GETMINMAXINFO 
EV_WM_GETTEXT 
EV_WM_GETTEXTLENGTH 


_ Response function declaration 


void EvActivate(uint active, bool minimized, HWND hWndOther) 


void EvActivateApp(bool active, HANDLE threadId) (WIN32 
only) 


void EvActivateApp (bool active, HTASK hTask) (WIN16 only) 
void EvAskCBFormatName(uint bufLen, char far* buffer) 

void EvCancelMode ( ) 

vold EvChangeCBChain(uint bufLen, char far* buffer) 

void EvChar(uint key, uint repeatCount, uint flags) 

int EvCharToItem(uint key, HWND hWndListBox, uint caretPos) 
void EvChildActivate () 

void EvChildInvalid(HWND) 

void EvClose() 

void EvCompacting(uint compactRatio) 


LRESULT EvCompareItem(uint ctrlId, COMPAREITEMSTRUCT far& 
compareInfo) 


int EvCreate(CREATESTRUCT far &) 
HBRUSH EvCtlColor (HDC, HWND hWndChild, uint ctlType) 
void EvDeadChar(uint deadKey, uint repeatCount, uint flags) 


vold EvDeleteItem(uint ctrlIid, DELETEITEMSTRUCT far& 
deleteInfo) 


void EvDestroy ( ) 

void EvDestroyClipboard() 

void EvDevModeChange (char far* devMode) 

void EvDrawClipboard( ) 

void EvDrawltem(uint ctrlId, DRAWITEMSTRUCT far& drawInfo) 
void EvDropFiles(TDropInfo dropInfo) 

void EvEnable (bool enabled) 

void EvEndSession(bool endSession) 

void EvEnterIdle(uint source, HWND hWndDlg) 
bool EvEraseBkgnd (HDC) 

void EvFontChange ( ) 

uint EvGetDlgCode (MSG far*) 

HFONT EvGetFont () ; 

void EvGetMinMaxInfo (MINMAXINFO far &) 

void EvGetText (uint bufLen, char far* buffer) 


uint EvGetTextLength() (WIN32 only) 
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~ Table 3.11. Standard Windows messages (continued) 


EV_WM_HOTKEY > 
EV_WM_HSCROLL 
EV_WM_HSCROLLCLIPBOARD 


EV_WM_ICONERASEBKGND 
EV_WM_INITMENU 
EV_WM_INITMENUPOPUP 


-EV_WM _INPUTFOCUS 
EV_WM_KEYDOWN 
EV_WM_KEYUP 
EV_WM_KILLFOCUS 
EV_WM_LBUTTONDBLCLK 
EV_WM_LBUTTONDOWN 
EV_WM_LBUTTONUP 
EV_WM_MBUTTONDBLCLK 
EV_WM_MBUTTONDOWN 
EV_WM_MBUTTONUP 
EV_WM_MDIACTIVATE 
EV_WM_MDICREATE 
EV_WM_MDIDESTROY 
EV_WM_MENUCHAR 
EV_WM.MENUSELECT > 
EV_WM_MEASUREITEM 


EV_WM_MOUSEACTIVATE 


EV_WM_MOUSEMOVE 
EV_WM_MOVE 

EV_WM_NCACTIVATE 
EV_WM_NCCALCSIZE 


EV_WM_NCCREATE 
EV_WM_NCDESTROY 
EV_WM_NCHITTEST 
EV_WM_NCLBUTTONDBLCLK 
EV_WM_NCLBUTTONDOWN 
EV_WM_NCLBUTTONUP 
EV_WM_NCMBUTTONDBLCLK 
EV_WM_NCMBUTTONDOWN 
EV_WM_NCMBUTTONUP 
EV_WM_NCMOUSEMOVE 
EV_WM_NCPAINT 
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void EvHotKey (int idHotKey) 


void EvHScroll(wint scrollCode, uint thumbPos, HWND hWndct1) 


void EvHScrollClipboard(HWND hWndCBViewer, uint scrollCode, 
uint pos) 


void EvIconEraseBkgnd (HDC) 
void EvInitMenu (HMENU) 


void EvInitMenuPopup (HMENU hPopupMenu, uint index, bool 
sysMenu) 


void EvInputFocus (bool gainingFocus) (WIN32 only) 

void EvKeyDown (uint key, uint repeatCount, uint flags) 

void EvKeyUp(uint key, uint repeatCount, uint flags) 

void EvKillFocus (HWND hwWndGetFocus) 

void EvLButtonDb1Clk(uint modKeys, TPoint& point) 

void EvLButtonDown(uint modKeys, TPoint& point) 

void EvLButtonUp(uint modKeys, TPoint& point) 

void EvMButtonDb1Clk(uint modKeys, TPoint& point) 

void EvMButtonDown(uint modKeys, TPoint& point) 

void EvMButtonUp(uint modKeys, TPoint& point) 

void EvMDIActivate (HWND hindActivated, HWND hWindDeactivated) 
LRESULT EvMDICreate (MDICREATESTRUCT far& createStruct) 

void EvMDIDestroy (HWND hWnd) 

uint EvMenuChar(uint nChar, uint menuType, HMENU hMenu) 
void EvMenuSelect (uint menuItemId, uint flags, HMENU hMenu) 


void EvMeasureItem(uint ctrlId, MEASUREITEMSTRUCT far& 
measurelInfo) 


uint EvMouseActivate(HWND hWndTopLevel, uint hitTestCode, 


uint msg) | 
void EvMouseMove(uint modKeys, TPoint& point) 
void EvMove(TPoint &clientOrigin) 

bool EvNCActivate(bool active) 


ulnt EvNCCalcSize(bool calcValidRects, NCCALCSIZE PARAMS far 
&) 


bool EvNCCreate(CREATESTRUCT far &) 


void EvNCDestroy () 


uint EVNCHitTest (TPoint& point) 

void EvNCLButtonDblClk(uint hitTest, TPoint& point) 
void EvNCLButtonDown(uint hitTest, TPoint& point) 
void EvNCLButtonUp(uint hitTest, TPoint& point) 
void. EvNCMButtonDb1Clk(uint hitTest, TPoint& point) 
void EvNCMButtonDown(uint hitTest, TPoint& point) 
void EvNCMButtonUp(uint hitTest, TPoint& point) 
void EvNCMouseMove(uint hitTest, TPoint& point) 
void EvNCPaint () | | 


Table 3. We solace tows mnessage®: eal 


Macro. 


EV. _WM. NCRBUTTONDBLCLK > 


EV_WM_NCRBUTTONDOWN 
EV_WM_NCRBUTTONUP 


EV_WM_OTHERWINDOWCREATED 
EV_WM_OTHERWINDOWDESTROYED 


EV_WM_PAINT 
EV_WM_PAINTCLIPBOARD 


EV_WM_PAINTICON 
EV_WM_PALETTECHANGED 


EV_WM_PALETTEISCHANGING 


EV_WM_PARENTNOTIFY 


EV_WM_POWER 
EV_WM_QUERYDRAGICON 
EV_WM_QUERYENDSESSION 


EV_WM_QUERYNEWPALETTE 


EV_WM_QUERYOPEN 
EV_WM_RBUTTONDBLCLK 
EV_WM_RBUTTONDOWN 
EV_WM_RBUTTONUP 


EV_WM_RENDERALLFORMATS 


EV_WM_RENDERFORMAT 
EV_WM_SETCURSOR 


EV_WM_SETFOCUS 
EV_WM_SETFONT 

EV_WM SETTEXT 
EV_WM_SHOWWINDOW 
EV_WM SIZE 
EV_WM._SIZECLIPBOARD 
EV_WM_SPOOLERSTATUS 
EV_WM_SYSCHAR 
EV_WM_SYSCOLORCHANGE 
EV_WM_SYSCOMMAND 
EV_WM_SYSDEADCHAR 
EV_WM_SYSKEYDOWN 
EV_WM_SYSKEYUP 
EV_WM_SYSTEMERROR 
EV_WM_TIMECHANGE 
EV_WM_TIMER 
EV_WM_VKEYTOITEM 
EV_WM_VSCROLL 


word Fey Lomo ine: hitTest, “Points oe 


void void EvNCRButtonDown(uint hitTest, TPoint& point) 
void EvNCRButtonUp(uint hitTest, TPoint& point) 

void EvOtherWindowCreated(HWND hWndother) (WIN32 only) 
void EvOtherWindowDestroyed(HWND hWndOther) (WIN32 only) 
void EvPaint () 


void EvPaintClipboard(HWND, HANDLE hPaintStruct) (WIN32 
only) 


void EvPaintIcon(}) 
void EvPaletteChanged(HWND hWndPalChg) 
void EvPaletteIsChanging (HWND hWndPalChg) 


void EvParentNotify(uint event, uint childHandleOrx, uint 
childIDOryY) 


int EvPower(uint powerEvent) 

HANDLE EvQueryDragIcon ( } 

bool EvQueryEndSession|( ) 

bool EvQueryNewPalette ( ) 

bool EvQueryOpen ( ) 

void EvRButtonDb1Clk(uint modKeys, TPoint& point) 
void EvRButtonDown(uint modKeys, TPoint& point) 
vold EvRButtonUp(uint modKeys, TPoint& point) 
void EvRenderAl1lFormats ( ) 

void EvRenderFormat (uint dataFormat) 


bool EvSetCursor (HWND hWndCursor, uint hitTest, uint 
mouseMsg) 


void EvSetFocus (HWND hWndLostFocus) 

void EvSetFont (HFONT hFont, bool redraw) 

void EvSetText (char far* text) 

void EvShowWindow(bool show, uint status) 

void EvSize(uint sizeType, TSize& size) 

void EvSizeClipboard(HWND hWndViewer, HANDLE hRect) 

void EvSpoolerStatus(uint jobStatus, uint jobsLeft) 

void EvSysChar(uint key, uint repeatCount, uint flags) 

void EvSysColorChange ( ) 

void EvSysCommand(uint cmdType, TPoint& point) 

void EvSysDeadChar(uint key, uint repeatCount, uint flags) 
void EvSysKeyDown(uint key, uint repeatCount, uint flags) 
void EvSysKeyUp(uint key, uint repeatCount, uint flags) 
void EvSystemError(uint error) 

void EvTimeChange ( ) 

void EvTimer(uint timerId) | 

int EvVKeyToItem(uint key, HWND hWndListBox, uint caretPos) 
void EvVScroll(uint scrollCode, uint thumbPos, HWND hWndct1l) 
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Table 3.11 Standard Windows messages (continued) 


-EV_WM_VSCROLLCLIPBOARD 7 void EvVScrollClipboard (HWND ‘hiWindCBViewer,, uint scrollCco 
uint pos) 

EV_WM_WINDOWPOSCHANGED void EvWindowPosChanged (WINDOWPOS far &windowPos) 

EV_WM_WINDOWPOSCHANGING void EvWindowPosChanging (WINDOWPOS far &windowPos) 

EV_WM_WININICHANGE void EvWinIniChange(char far* section) 


These macros handle WM_VBXFIREEVENT messages generated by VBX controls. 
EvHandler is a generic term for a specific VBX control message (such as EvClick). 


Table 3.12 | VBX messages 


EV_VBXEVENTNAME ID, event, EvHandler void EvHandler(VBXEVENT FAR *event) 
EV_VBXEVENTINDEX ID, event, EvHandler void EvHandler(VBXEVENT FAR *event) 


These macros handle user-defined messages: 


Table 3.13 User-defined messages 


EV_MESSAGE UserMessage, UserName LRESULT UserName (WPARAM, LPARAM) 
EV_REGISTERED Registered name, UserName — LRESULT UserName (WPARAM, LPARAM) 


Some event-handling functions or messages have no predefined names. In these cases, 
the generic term UserName is used to indicate that you can use any function name you 
want to as long as the function's signature matches the signature required by the 
response table macro. Similarly, the term UserMessage indicates that you can define your 
own message ID. 


The descriptions of these macros and functions use the following conventions when 
listing the arguments of the message macros: 


° ID refers to the child window's ID (for example, ID_GROUPBOX) 
e CMD ID refers to the command ID (for example, CM_FILENEW) 
¢ Code refers to the notification code (for example, BN_CLICKED) that is being sent. 
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ObjectWindows dispatch functions 


Dispatch functions separate the [Param and wParam parameters of Windows messages 
into their respective data types and pass control to an ObjectWindows member function. 


For example, when Windows sends an application a WM_CTLCOLOR message, the 
wParam is really an HDC, and the /Param has a HWND and a uint hidden inside. After 
the dispatch function cracks the wParam and lParam parameters into their constituent 
parts, it dispatches the Windows WM_CTLCOLOR message to the following 
ObjectWindows member function: 


HBRUSH EvCtlColor(HDC, HWND, uint); 


Although dispatch functions are written for specific Windows API messages, they have 
no knowledge of the actual Windows messages they are cracking. Instead, at run time, 
TEventHandler::Dispatch calls the appropriate dispatch function which then cracks the 
message and calls the appropriate member function, using the response table's pmf 
(pointer to a member function). These dispatch functions are never called directly. 


The following four parameters are common to all dispatch functions: 

e GENERICG& generic is the pointer to the object (for example, TEdit). 

¢ GENERIC::*pmf is the pointer to the member function (for example, EvActivate). 
e WPARAM is one of the message parameters the dispatch function cracks. 

¢ LPARAM is one of the message parameters the dispatch function cracks. 


The name of the dispatch function used in the response table entry or macro depends on 
the type of message cracking the function performs. The first letter of the name indicates 
the return type (for example, U indicates an unsigned integer). The second group of 
letters signifies the arguments of the function (for example, POINT of type TPOINT, or 
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-|_LPARAM_Dispatch 


U of type uint). The following table lists the abbreviations of the member functions’ 
- signatures and their corresponding data types. | 


1 int 

V void 

H HANDLE (same as uint in size) 
132 int32 | 
POINT TPoint& (TPoint object constructed) 
POINTER void* (model's ambient size) 

U uint 


Message crackers that serve customized messages have names based on the specific 
message they crack. For example, the message cracker for WM_MDIACTIVATE 
messages has the following prototype: 


int32_v_MdiActivate_Dispatch(GENERIC& generic, HBRUSH (GENERIC::*pmf) (uint, uint), 
ulnt wParam, int32 lParam); 


ObjectWindows uses the same dispatch functions for messages that require the same 
type of cracking. For example, both the WM_HSCROLL and WM_VSCROLL event 
handlers have void (*)( uint, uint, HWND) as their signature. The Windows message 
also has the wParam and [Param parameters in the same place. Therefore, 
ObjectWindows uses the same dispatch functions for both of these messages. 


The following aliases have been defined for purposes of backward compatibility: 


#define HBRUSH_HDC_W_U_Dispatch U_U_U_U_Dispatch 
#define LRESULT_U_U_W_Dispatch 132_MenuChar_Dispatch 
#define LRESULT_WPARAM_LPARAM Dispatch 132_WPARAM_LPARAM_Dispatch 
#define v_U_B_W_Dispatch v_Activate_Dispatch 
#define v_W_W_Dispatch v_MdiActivate_Dispatch 
See also 
TEventHandler 


List of ObjectWindows dispatch functions 


— int82 | LPARAM _Dispatch(GENERIC& generic, int (GENERIC::*pmf)(int32), uint wParam, int32 |Param); 
Passes /Param as an int32 and returns an int. 


int32 i U_W_U Dispatch(GENERIC& generic, int (GENERIC::*pmf)(uint, uint, uint), uint wParam, int32 |Param); 
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i WPARAM_Dispatch 
For Win32, passes wParam.lo (the LOWORD of wParam) as a uint, /Param as a uint and 
wParam.hi (the HIWORD of wParam) as a uint and returns an int. For Win16, passes 
wParam as a uint, |Param.lo as a uint and |Param.hi as a uint and returns an int. This is a 


semi-customized dispatch function used for WM_CHARTOITEM and 
WM_KEYTOITEM messages. 


i WPARAM Dispatch Dispatch.h 


int32 i WPARAM_Dispatch(GENERIC& generic, int (GENERIC::*pmf)(uint), uint wParam, int32 |Param); 
Passes wParam as a uint and returns an int. 


int32 132 _Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(), uint, int32); 
This dispatcher passes nothing and returns an int32. 


int32 132_LPARAM_Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(int32), uint, int32 |[Param); 
This dispatcher passes /Param as an int32 and returns an int32. 


int32 132. WPARAM LPARAM _Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(uint, int32), 
uint wParam, int32 |Param); 


This dispatcher passes wParam as a uint and [Param as an int32, and returns an int32. 


int82 132_MenuChar_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, uint, uint), uint wParam, 

int32 IParam); | 
Cracker for WM_PARENTNOTIFY messages. Passes three uints and returns an int32. 
Under Win322, the first uint is wParam.lo, the second uint is wParam.hi, and the uint is 
IParam. Under Win 16, the first uint is wParam, the second uint is /Param.lo, and the third 
uint is /Param.hi. 


_ [82_U_Dispatch | Dispatch.h 


int32 132 _U Dispatch(GENERIC& generic, int82 (GENERIC::*pmf)(uint), int32 [Param); 
This dispatcher passes /Param and uint and returns an int32. 


U Dispatch Dispatch.h 


int32 U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (), uint wParam, int32 IParam); 
Passes no arguments and returns a uint. 
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U_LPARAM_Dispatch 


int32 U_LPARAM_Dispatch(GENERIC& generic, uint (GENERIC: *pmf) (int32), uint wParam, int32 Param); 
Passes [Param as an int32 and returns a uint. 


U POINT Dispatch - Dispatch.h 


int32 U POINT Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (TPoint&), uint wParam, int32 |Param); 
Passes lParam as a TPoint& and returns a uint. 


U POINTER Dispatch | | Dispatch.h 
int32 U_POINTER_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (void*), uint, int32 [Param); 

Passes [Param as a void*:and returns a uint. 

U_U Dispatch Dispatch.h 


int32 U_U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint), uint, int32 [Param); 
Passes /Param asa uint and returns a uint. 


UUUU Dispatch a Dispatch.h 


int82 U_U_U_U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, uint, uint), uint wParam, 
int32 |Param); 


Passes three uints and returns a uint. The first uinti is wParam, the second uint is the 
LOWORD of Param, and the third uint is the HIWORD of /Param. 


U WPARAM_LPARAM Dispatch Dispatch.h 


int32 U_WPARAM_ LPARAM Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, int32), 
uint wParam, int32 IParam); 
Passes wParam as a uint and [Param as an int32 and returns a uint. 


int32 v_Activate Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, 
int32 IParam); 
Cracker for WM_ACTIVATE messages. Passes three uints and always returns 0. Under 
-Win32, the first uint is wParam.lo, the second uint is wParam.hi, and the third uint is 
lParam. Under Win16, the first uint is wParam, the second uint is /Param.hi, and the third 
uint is /Param.lo. 


int32 v_Dispatch (GENERIC& generic, void (GENERIC::*pmf) (), uint uint, int32); 
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v_ LPARAM_Dispatch 


Passes nothing and always returns 0. 


int32 v_ LPARAM Dispatch (GENERIC& generic, void (GENERIC::*pmf) (int32), uint wParam, int32 IParam); 
Passes /Param as an int32 and always returns 0. 


int32 v_MdiActivate_Dispatch(GENERIC& generic, void (GENERIC::*pmf}(uint, uint), uint wParam, int32 |Param): 
Specifically designed to handle EvMDIActivate messages, v_MdiActivate_Dispatch passes 
two uints and always returns 0. Under Win32, the first uint is [Param and the second 
uint is wParam. Under Win16, the first uint is /Param.lo. If lParam is nonzero, the second 
uint is /Param.hi; otherwise, the second uint is wParam. | 


int32 v_ParentNotify Dispatch(GENERIC& generic, int(GENERIC::*pmf) (uint, uint, uint), uint wParam, 

int32 |Param); 
Performs message cracking for WM_PARENTNOTIFY messages, which notify a parent 
window that a given event has occurred in the child window. Passes three uints and 
always returns 0. For Win16, the first uint is wParam, the second uint is [Param.lo, and 
the third uint is /Param.hi. For Win32, if wparam.lo is a mouse message, then the first uint 
is wparam, the second uint is [param.lo, and the third uint is [Param.lu. Otherwise, the first 
uint is wparam.lo, the second uint is Param, and the third uint is wParam.hi. 


v_POINT “Dispatch Dispatch.h 
int32 v_ POINT Dispatch (GENERIC& generic, void (GENERIC::*pmf) (TPoint&), uint wParam, int32 |Param); 


Passes a reference to a POINT (TPoint&) and always returns 0. Under Win32, passes 
1Param; under Win16, passes a reference to /Param. 


int32 v_POINTER_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (void*), uint wParam, int32 lParam); 
Passes an /Param as a void* pointer and always returns 0. 


v_U Dispatch Dispatch.h 


int32 v_U_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, int32 rao 
Passes /Param as a uint and always returns 0. 
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vV_UL POINT _Dispatch 


~ int82 v_U_POINT Dispatch(GENERIC8 generic, void (GENERIC: mf) (uint, TPoint&), uint wParam, 
int32 ‘|Param); 
Passes wparam as a uint and [Param asa reference to a POINT and always returns 0. 


int32 v_U_U_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint), uint wParam, int32 |Param); 
Passes two uint and always returns 0. The first uint is wParam and the second uint is 
1Param. | 


int32 v U UU Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, 


int32 IParam); 
Passes three uints and always returns 0. The first uint is wParam, the second uint is 
1Param.lo and the third uint is /Param.hi. 


int32 v_U_U_W_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, 

— int82 |Param); 
Passes three uints and always returns 0. Under Win32, the first uint is wParam.lo., the 
second uint is wParam.hi, and the third uint is [Param Under Win16, the first uint is 
wParam, the second uint is [Param.lo, and the third uint is /Param.hi. This is a semi- 
customized message cracker for WM_HSCROLL, WM_VSCROLL, and 
WM_MENUSELECT messages. 


v_WPARAM Dispatch Dispatch.h 


int32 v WPARAM_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (i, uint wParam, int32 |Param); 
Passes wParam as a uint and always returns 0. 


int32 v -WPARAM. LPARAM _Dispatch(GENERIC& generic, eid (GENERIC::*pmf) (uint, int32), uint wParam, 
int32 IParam); 
Passes wParam as a uint and [Param as an int32 and always returns 0. 


518 ObjectWindows Reference Guide 


S 


SS 
Ss 


ObjectComponents reference 


Part Il, ObjectComponents reference 519 


520 ObjectWindows Reference Guide 


Overview of ObjectComponents 


This chapter lists alphabetically the ObjectComponents classes, macros, constants, data 
types, and registration keys. The header file that defines each entry is listed opposite the 
entry name. Class members are grouped according to their access specifiers—public or 
protected. Within these categories, data members, then constructors and destructors, 
and member functions are grouped separately and listed alphabetically. 


The members listed for each class include only those that are new or redefined in the 
class itself. Members inherited from a base class are not listed again in the derived class. 
No private members are listed. In some cases members that are public or protected are 
omitted as well because they are meant only for the use of other ObjectComponents 
classes. 


Some entries related to ObjectComponents programs appear in other sections of this 
book. OLE-enabled ObjectWindows classes, such as TOleWindow and TOleFactory, are 
listed with the other ObjectWindows classes. Registration macros and some locale items 
are listed later in the Object Support Library (OSL) reference. 


ObjectComponents libraries 


These are the libraries an ObjectComponents application uses for linking. 


‘OCFWM. | jectCompone 
OWLWM.LLIB OWLWL.LIB OWLWLLIB ObjectWindows 
BIDSM.LIB BIDSL.LIB BIDSIL.LIB Class libraries 
OLE2W16.LIB OLE2W16.LIB OLE2W16.LIB OLE system DLLs 
IMPORT.LIB IMPORT.LIB IMPORT.LIB Windows system DLLs 
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ObjectComponents header files 


MATHWM.LIB MATHWL.LIB | Math support 
CWM.LIB CWL.LIB CRTLDLL.LIB C run-time libraries 


ObjectComponents header files 


Header files, located in your INCLUDE/OCF subdirectory, contain declarations for 
class functions and definitions for data types and constants. 


appdesch = TAppDescriptor, TComponentFactory 


autodefs.h Classes and structs used for automation 
automacr.h Macros for automation declarations and definitions 


ocapp-h OC_APPxxxx messages, TOcApp, TOcFormatName, TOcHelp, TOcMenuDescr, TOcModule, 
TOcNameList, TOcRegistrar, WM_OCEVENT message 


ocapp.th IDS_CFxxxx resource IDs for strings describing standard Windows clipboard formats 
ocdefs.h TXObjComp, HR_xxxx result codes, declaration specifiers 

ocdoc.h TOcDocument 

ocfevx.h Message cracker macros for WM_OCEVENT messages 

ocfpch.h #include statements for all ObjectComponents headers, used with pre-compiled headers — 


ocobject.h TOcAspect, TOcDialogHelp, TOcDropAction, TOcInitHow, TOcInitInfo, TOcInitWhere, 
TOcInvalidate, TOcPartName, TOcScrollDir 


ocpart.h TOcPart, TOcPartCollection, TOcPartCollectionIter, TOcVerb 


ocreg.h OCxxxx global pungHOne, OCrxxxx registration constants, TAppMode enum, TRegistrar, 
TXRegistry 


ocremvieh TOcRemView 
ocstorag.h TOcStream, TOcStorage 


ocview.h OC_VIEWxxxx messages, TOcDragDrop, TOcFormat, TOcFormatList, TOcFormatListlter, 
TOcSaveLoad, TOcScaleFactor, TOcToolBarInfo, TOcView, TOcViewPaint 


oleutil.h DECLARE COMBASES# macros, TOleAllocator, Tunknown, TXOle 


General OLE classes, macros, and type definitions 


ObjectComponents provides the following utility items for use in building OLE 
applications, whether they support linking and embedding or automation. 


HR_xxxx macros 


_ICLASS macro Specifier for declaring a class that implements an OLE interface 
_IFUNC macro | Specifier for declaring OLE functions 
_OCFxxxx macros Specifiers for declaring ObjectComponents classes 


TComponentFactory typedef Callback function where an application creates objects that OLE requests 
TLocaleld typedef Data type for language setting identifiers 
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Global utility functions 


Item : a ee cee Meaning — oe 

TOleAllocator class Establishes a | memory rallocator for OLE to use 

TUnknown class _ Implements the fundamental [Unknown interface required of all OLE 
: objects 


Global utility functions 


The items in this table are utility functions that ObjectComponents declares globally. 


Item Purpose : SS AO 
DynamicCast Converts a pointer from one aipe to another if both ape are related inroueh hoe 
MostDerived Returns a pointer to the most derived class type that fits a given object 


ObjectComponents exception classes 


ObjectComponents throws the types of exceptions shown in this list. All the exception 
classes derive from TXBase. 


‘Class Purpose, 

TXAuto Exceptions that occur during automation 

TXObjComp — Exceptions that occur during ObjectComponents linking and embedding operations 
TXOle Exceptions that occur while processing OLE API commands 


TXRegistry Exceptions that occur while using the system registration database 


Automation classes 


ObjectComponents provides the following classes that support automation. 


‘Class oe Purpose — se 

TAutoBase - Base class for denving automated a obece® 

TAutoCommand Holds all the data for one command received by an automation server 

TAutoEnumerator<> Lets an automation controller enumerate items in a server's collection 

TAutolterator Lets an automation server iterate items in an automated collection 

TAutoObject<> Creates a smart pointer to an automated object 

TAutoObjectByVal<> Lets an automation server automate a method that returns an object by value 
(not by reference) 

TAutoObjectDelete Lets an automation server automate a method that returns an object 

TAutoProxy Base class for deriving the C++ objects an automation controller creates to 
represent the OLE objects it wants to control 

TAutoStack Holds a set of TAutoCommand objects each representing a command received by 
an automation server 
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Automation enumerated types and type definitions 


TAutoVal Holds the data from a VARIANT union, the data format ve uses for sending 
automation commands | 
TRegistrar Manages system registration tasks for an.automation application 


Automation enumerated types and type definitions 


ObjectComponents provides the following items that support automation. 


AutoDataTypeenum Identifiers for automation data types 
ObjectPtr typedef void pointer to a C++ object 


Automation data types 


ObjectComponents provides the following data types that support automation. To use 
these data types, see Declarations and Definitions. 


TAutoBool struct 
TAutoCurrency struct 
TAutoDate struct 
TAutoDouble struct 
TAutoFloat struct 
TAutoInt 
TAutoLong struct 
TAutoShort struct 
TAutoString struct 
TAutoStruct struct 
TAutoVoid struct 


An automation data type is a structure that exists solely to describe a single type of data. 
Automation definitions use these structures to assist in converting parameters and 
return values between the VARIANT unions that OLE uses and the C++ data types that 
your programs use. 


For the most part, although they are structures, you cannot create instances of them 
because they lack constructors and contain only a single static member. They all derive 
from TAutoType and inherit its GetType method. The only thing most of these structures 
do is respond to GetType calls by returning the static ID for a data type. 
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Automation declaration macros 


The following table lists C++ data types that might appear in your programs and the 
corresponding data types that you should use in automation declarations 
(DECLARE _AUTOCLASS) and definitions. (DEFINE_AUTOCLASS.) 


short 
unsigned short 
long 

unsigned long 
int 

unsigned int 
float 

double 

bool (or int) 
TAutoDate 
TAutoDate far * 


TAutoCurrency 
far* 


char* 

const char* 
char far* 
const char far* 
string 

enum 

Ai Ria 

T& 

const T* 

const T& 

T* (returned) 
T& (returned) 
T (returned) 
void (no return) 
short far* 

long far* 

float far* 


double far* 


_ Declarationtype 


short 


short or unsigned 


long 


unsigned long 

int 

int or long 

float 

double 

TBool 

TAutoDate 
TAutoDate far* 
TAutoCurrency far* 


TAutoString 
TAutoString 
TAutoString 
TAutoString 

string 

short or int 
TAutoObject<T> 
TAutoObject<T> 
TAutoObject<const T> 
TAutoObject<const T> 
TAutoObjectDelete<T> 
TAutoObjectDelete<T> 
TAutoObjectBy Val<T> 
(use AUTOFUNCXV macros) 
short far* 

long far* 

float far* 

double far* 


Automation declaration macros 


Definition type 
TAutoShort 

TAutoShort or TAutoLong 
TAutoShort 

TAutoLong (treated as signed long) 
TAutoInt 

TAutolnt or TAutoLong 
TAutoFloat 

TAutoDouble 

TAutoBool 

TAutoDate 

TAutoDateRef 
TAutoCurrencyRef 


TAutoString 

TAutoString 

TAutoString 

TAutoString 

TAutoString 

TAutoShort or user-defined AUTOENUM 
T (class T must be automated) 

T (class T must be automated) 

T (class T must be automated) 

T (class T must be automated) 
(C++ object deleted if no refs) 
(C++ object deleted if no refs) 

T (T copied, deleted when refs==0) 
TAutoVoid 

TAutoShortRef 

TAutoLongRef 

TAutoFloatRef 

TAutoDouble Ref 


ocf/automacr.h 


To make parts of an automated class accessible to OLE, an automation server adds 
declaration macros to the declaration of the C++ class and definition macros to the 
implementation of the C++ class. The declaration macros create command objects for 


executing commands sent by the controller. 
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Automation definition macros 


The block of automation dsslaevion macros always begins with 
DECLARE_AUTOCLASS. There is no need for a matching END macro to close the 
declaration. 


DECLARE_AUTOCLASS(cls) | The macros that follow declare automatable members of the user- 
| defined class cls. 


Declaration macros 
After DECLARE AUTOCLASS comes a series of macros, one for each class member 


that you choose to expose. Which a macros you choose depends on what the 
members are. 


“AUTODATA 
AUTOFLAG A bit flag 
AUTOFUNC Function 
AUTOITERATOR Iterator object 
AUTOPROP Property 
AUTOSTAT | Static member or global function 
AUTOTHIS “this 
AUTODETACH macro 


In addition, an automation declaration can also include the AUTODETACH macro. This 
macro does not expose a class member. It invalidates external references when the object 
is destroyed. , 


Automation definition macros _ ocflautomacrh 


To make parts of an automated class accessible to OLE, an automation server adds 
declaration macros to the declaration of the C++ class and definition macros to the | 
implementation of the C++ class. 


The block of automation definition macros begins with DEFINE_AUTOCLASS and 
ends with END_AUTOCLASS, unless the object is, inherits from, or delegates to a 
Component Object Model (COM) object. In that case, the block of automation definition 
macros begins with DEFINE_AUTOAGGREGATE and ends with 
END_AUTOAGGREGATE. 


DEFINE_AUTOCLASS(cls) The macros that follow define automatable members of 


the user-defined class cls. 


END_AUTOCLASS(cls, name, doc, help) The C++ class cls is exposed to OLE controllers under 
| the name name. If the user asks OLE about the object 
name, the system returns the string in doc. If a .HLP file 
is registered for the object, then the context ID in help 
points to a screen that describes the object. — 
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Automation hook macros 


Beers 


Macro ee oe : Meaning _ 


DEFINE "AUTOAGGREGATE(ds, wets The macros that follow define pismatepe members of 
the user-defined class cls, which is, inherits from, or 
delegates to a COM object. 


END _AUTOAGCREGATE(ds, name, doc, help) Same as END_AUTOCLASS. 


Between the DEFINE and END macros comes a series of other macros describing each 
exposed data member or function. The macros implement methods for a class nested 
within your automated class. When ObjectComponents receives commands from a 
controller, it passes them to the nested class. The macros build wrapper functions in the 
nested class that enable it to call your own class directly. 


Which particular macros you choose depends on what the members are. 


Member  —_—_séDecclaration macro 2 
Automated application EXPOSE_APPLICATION eer 
Auxiliary class EXPOSE_DELEGATE Macro 

Base class EXPOSE_INHERIT Macro 
Collection iterator EXPOSE_ITERATOR Macro 
Method EXPOSE_METHOD Macros 


Read-only property EXPOSE_PROPRO 
Read-write property EXPOSE_PROPRW 
Write-only property EXPOSE_PROPWO 


Shutdown method EXPOSE_QUIT 
Automation hook macros ocflautomacr.h 


These macros establish hooks to be invoked every time a particular automation 
command is executed. They are never used by themselves but always as the last 
parameter of some other automation declaration macro. If you add one of these hooks to 
the declaration of some exposed class member, then every time an automation 
controller attempts to execute that command, ObjectComponents first executes the code 
in the hook. The code can be a simple expression or it can contain calls to other 
functions. 


Most of the macros expect to receive some expression or code as a parameter. Often the 
code or expression in the macro needs to refer to the arguments passed in or to the value 
of an automated data member. Within the macro expression, write Arg1, Arg2, Arg3... to 
refer to the received arguments. Write Val to refer to an automated data member. 


Macro _ fo . - : = ao Meaning — rrr 

AUTONOHOOK - Use this macro, athe aipumenieyt to prevent anyone on ieokane. | 
the command. Not even ObjectComponents can monitor the call. (For 
advanced uses only.) 

AUTOINVOKE(code) The code here is executed each time the automation command is 


executed. Create an AUTOINVOKE hook if you want to override the 
normal execution sequence. 
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Automation proxy macros 


AUTORECORD (code) The code inserted here creates a record of the commands executed sO 
| that the sequence can be stored and replayed. 
AUTOREPORT (code) The code inserted here returns an error code from the automated — 


member. If code evaluates to 0, OLE assumes the command succeeded. If 
code evaluates to a nonzero value, then OLE throws an exception that 
returns an error code to the controller. 


Within the code expression, use Val to refer to the actual value returned. 
AUTOUNDO\(code) The code inserted here creates a TC Onan object that will undo 
the action of the current command. 


| AUTOVALIDATE(condition) The code here should evaluate to true if the arguments received are 
. valid for the command and false otherwise. If the expression returns _ 
false, OLE throws an exception that returns an error code to the 
controller application. 


Example 
This declaration ensures that an automated data member is never assigned a value 
outside a given range. 


AUTODATA (Number, Number, short, 
AUTOVALIDATE (Val>=NUM_MIN && Not TooBig (Val) Ve 


Automation proxy macros -ocflautomacr.h 


An automation controller creates a proxy object (derived from TAutoProxy) to represent 
an automated OLE object. For every command the controller wants to send the object, it 
adds a method to the proxy object. The proxy methods mimic the commands the object 
supports. When the controller calls proxy methods, ObjectComponents sends 
automation commands through OLE. 


The implementation of a proxy method always contains three macros: an 
AUTONAMES macro, an AUTOARGS macro, and an AUTOCALL macro. 
AUTONAMES associates names with arguments. AUTOARGS describes any 
arguments that do not have names. The use of names makes it possible to send partial 
sets of arguments and let the server assign default values to the remaining arguments. 


The third macro, AUTOCALL, tells whether the command represents a method or a 
property of the automated object and whether the command returns a value. 


To generate proxy object declarations and definitions directly, use the TYPEREAD.EXE 
tool (located in the OCTOOLS subdirectory.) TYPEREAD scans the type library of an 
automation server and generates complete proxy code for controlling the server. 


You are free to subsititute your own code for the standard macros in order to handle 
special situations. 


AUTONAMES Associates names with arguments so the caller can choose to pass only selected 
7 arguments 
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Registration keys 


) Macro _ Lae Description ; es 
AUTOARGS Describes arguments that do not have names 
AUTOCALL Tells whether the command is a method or a property and whether it returns a value 


Registration keys 


Most ObjectComponents programs build registration tables describing their OLE 
capabilities. (Only automation controllers can omit this step.) The registration tables 
contain keys paired with values. The keys are standard. You decide which ones to 
register and you supply values for them. 


Which keys you choose depends on whether your application is a server, a container, or 
an automation program. Some keys must be registered and some are optional. 
Furthermore, some apply only to the application's primary registration table, and others 
apply to the tables for each of the application's document types. 


A registration table starts with the BEGIN_REGISTRATION macro and ends with 
END_REGISTRATION. In between is one macro for each key you want to register. The 
macro depends on the key. Most keys use the REGDATA macro, but there are others 
such as REGFORMAT and REGSTATUS. 


If your application is a server, most of the information in its registration tables is 
recorded in the system's registration database. Putting the information there makes it 
possible for OLE to learn much about the server without actually loading the 
application into memory. For example, if an automation controller asks for information 
about the commands an automation server supports, OLE can locate the server's type 
library from an entry in the database. 


] Key . o Meaning : : . 6 a a - 7 . _ oe : 

aspectall | Option flags that apply to all presentation aspects. 

aspectcontent Option flags for the content view of an object. 

aspectdocprint Option flags for the printed document view of an object. 

aspecticon Option flags for the iconic view of an object. 

aspectthumbnail Option flags for the thumbnail view of an object. 

clsid A GUID identifying the application. 

cmdline Arguments OLE should place on the command line when it launches the server. 

debugclsid A GUID identifying the debugging version of a server. This is always generated 
internally. You should never specify it directly. 

debugdesc A long string describing the debugging version of a program. 

debugger The file name and command line switches for loading your debugger. 

debugprogid A string naming the debugging version of a program. Defining this forces 
ObjectComponents to register debugging and non-debugging versions. 

description A string describing the application. / 

directory The default directory for browsing document files. 

docfilter File specification for listing files created by the application. 

docflags Option flags for the application's documents. 

extension A three-letter filename extension for files created by the server. 


Chapter 5, Overview of ObjectComponents 529 


t 
formatn 


C 


handler | 


helpdir 


iconindex 
insertable 


language 
menuname 


path 


permid 
permname 
progid 
typehelp 


usage 


verbn 
verbnopt 


version 


Linking and embedding classes 


A Clipboard format the application supports. (Use REGFORMAT to register Clipboard 
formats.) 


A full path pointing to a library that can draw objects created by the server. Defaults to 
OLE2.DLL. 


Full directory where online Help for the type library resides. 


An index telling which of the icons in the server's resources represents the DES of 
objects the server produces. (Use REGICON to register an icon.) - 


Indicates that the application serves its document for linking and embedding in 
container documents. 


Locale ID currently in effect. (Set internally during automation.) 
A short name for the server, used in a container's menu. 


The path where OLE looks to find the server. This key is set internally during 
registration. — 


A string that names the application without indicating any version. 


A string that describes the application without indicating any version. 


A string uniquely naming the application. 
Name of the file where online Help for the type library resides. 


Indicates the whether the server can support concurrent clients with a single 
application instance. 


A string naming an action the server can perform with its objects. 


Option flags describing the server's verbs. (Use REGVERBOPT to NSE verb 
options.) 


Version string for the application and type library. 


Linking and embedding classes 


ObjectComponents provides the following classes for use by applications that support 
linking and embedding. 


TOcApp Connector object that implements BOCOLE interfaces for the application 
TOcDocument Manages the parts in a container's compound document 
TOcFormatList List of Clipboard data formats a document supports 
TOcFormatListlter Iterator for the list of Clipboard data formats a document supports 
TOcFormatName Holds strings describing a single data format that an application might 
. encounter on the Clipboard (see TOcNameList) 
TOcModule Base class for deriving OLE-enabled application objects 
TOcNameList Contains a collection of strings describing all the data formats that an application 
might find on the Clipboard 
TOcPart Connector object that a container uses to represent an object linked or emibddded 
in one of its documents 
~ TOcPartCollection Manages a collection of linked or embedded parts 
TOcPartCollectionIter Iterator for the collection of parts linked or embedded in a single document 
TOcRegistrar 


Manages OLE registration tasks for a linking and embedding application 
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Linking and embedding classes 


Blagg ae es | Purpose _ eS 


TOcRemView | - Connector abject that a server uses to ‘aaa an object li linked 6 or fembedaed i ina 
container's document 


TOcScaleFactor Carries information from a container to a server requesting that linked or 
embedded objects be drawn to a certain scale 


TOcVerb Holds information about an action that a server is able to perform with its own 
objects when they are linked or embedded in a container 


TOcView A connector object that an application uses to draw its own documents in its 
own frame window 


A few of the ObjectComponents classes used for linking and embedding implement 
COM interfaces. (COM stands for Component Object Model. COM is the standard that 
defines what an OLE object is.) Most of the supported interfaces are not standard OLE 
interfaces; they are custom interfaces that communicate with OLE through the BOCOLE 
support library. But like any COM object they do implement [Unknown (by deriving 
from TUnknown). 


The classes that define COM objects for linking and embedding are TOcApp, TOcView, 
TOcRemView, and TOcPart. These classes connect your application to OLE. They are 
called connector objects. An ObjectComponents application must create connector objects 
in order to interact with other OLE applications. 


Figure 5.1 shows how the connector objects are related. 


Figure 5.1 Hierarchy of ObjectComponents connector classes 


TUnknown 


TOcView TOcPart 


TOcRemView 


-Nonvirtual inheritance Virtual inheritance 
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Linking and embedding enums 


ObjectComponents provides the following enumerated types for use by applications 
that support linking and embedding. 


TOcAppModeenum _ Flags identifying the application's running conditions 


TOcAspect enum Flags identifying object presentation aspects 
TOcDialogHelp enum Constants identifying standard OLE dialog boxes where a user can ask for help 


TOcDropAction enum Constants identifying actions that can result from dropping an object on a 
, window 


TOcInitHow enum Constants identifying the action a container is to take on receiving a new object— 
either link or embed 


TOcInitWhere enum Constants identifying places the data for an object can reside 


TOcInvalidateenum Flags indicating whether an object is invalid because of a change in its data or just 
in its appearance 


TOcPartNameenum Constants identifying different strings a container might request when asking for 
| the name of an object linked or embedded in it 


TOcScrollDir enum Constants identifying directions a container might be asked to scroll its window 


Linking and embedding messages 


ObjectComponents provides the following messages for use by so that 
eae linking and embedding. 


OC_APPxxxx Messages sent to an application object 


OC_VIEWxxxx Messages sent to a view object 
WM_OCEVENT _ Carries event signals from ObjectComponents to an application 


Linking and embedding structs 


ObjectComponents provides the following structs for use by applications that support 
linking and embedding. 


S in order to receive an ooject dropped on 1ts 


TOcInitInfo struct Holds information a container needs in order to place a new object in its 
document 


TOcMenuDeser struct Holds information about a shared menu where the container and server merge 
: their commands for in-place editing 


TOcSaveLoad struct Carries information an application needs to save or load a linked or embedded 
| object 
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Oocrxxxx constants 


TOcToolbarInfo struct Carries handles to a server's tool bars to be displayed in the container's window 
during in-place editing 

TOcViewPaint struct Carries information that tells a server how to repaint a linked or embedded object 
when the container invalidates part of the object's surface 


Ocrxxxx constants ocffocreg.h 


The ocreg.h header defines a number of constants used in constructing an application's 
registration tables. These constants all begin with ocr. They fall into several groups. Most 
of them are used with the REGFORMAT macro to describe the kinds of data transfers a 


document supports. 


ming 


: Aspect constants Data presentation modes (such as icon, content, or thumbnail) 


Clipboard constants Clipboard data formats (such as text, bitmap, or link source) 
Direction constants Data transfer directions (getting or setting) 

Limit constants Maximum number of items that can be registered 

Medium constants Data transfer mediums (such as disk file or Clipboard) 

Object status constants Aspect options (such as showing icon only or redrawing on resize) 
Usage constants Support for multiple clients (single use or multiple use) 


Verb attributes constants Verb option flags (never dirties and show on menu) 
Verb menu flags Verb display options (such as grayed, disabled, or menu bar break) 
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Modifies the declaration of an interface class, one that defines or implements an 
interface for OLE or for the BOCOLE support library. 


FUNC macro ttt 


Modifies the declaration of an OLE function. 


The _IFUNC macro controls function calling conventions and export declarations. 
Placing these macros in a keyword allows the compiler to choose the right combination 
of modifiers for a particular platform. 


ObjectComponents uses the macro to declare OLE and BOCOLE functions as well as 
member functions that wrap direct OLE and BOCOLE calls. 


_IFUNC serves the same purpose in Borland headers that the 
STDMETHODCALLTYPE serves in OLE system headers. 


_OCFxxxx macros _ ocfiocfdefs.h 


These macros are used internally to declare classes, functions, and data members in 
ObjectComponents classes. Their definitions vary depending on whether you build a 
16- or 32-bit EXE or DLL. Some of them also force the declaration to __huge. 
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aspectall registration key 


These macros closely match the corresponding _OWLxxxx macros. 


_OCFCLASS Exports or imports classes for DLLs. 
_OCFDATA Exports or imports data members for DLLs. 
_OCFFUNC Exports or imports member functions for DLLs. 


aspectall registration key 


Registers option flags that affect all views of an object. The flags control how all views of 
the object are presented. 


Linking and embedding servers can optionally register aspect status in their document 
registration tables. Aspect status does not apply to application registration tables, 
containers, or automation servers. 


To register flags for all aspects, use the REGSTATUS macro, passing "all" as the first 
parameter and an ocrxxxx object status enum value as the second parameter. 


REGSTATUS (all, ocrNoSpecialRendering) — 


_ See also 
aspectcontent registration key, aspectdocprint registration key, aspecticon registration 
key, aspectthumbnail registration key, ocrxxxx Object Status enum, REGSTATUS macro 


aspecicontent registration key 


Registers option flags for the content view of an object. The content view usually shows 
all the data in an object (or as much of the data as fits in the available space.) The option 
flags control how the content view is used. 


Linking and embedding servers can optionally register aspect status in their document 
registration tables. Aspect status does not apply to application registration tables, 
containers, or automation servers. 


To register flags for the content aspect, use the REGSTATUS macro, passing "content" as 
the first parameter and an ocrxxxx object status enum value as the second parameter. 


REGSTATUS (content, ocrRecomposeOnResize) 
See also 


aspectall registration key, aspectdocprint registration key, aspecticon registration key, 
aspectthumbnail registration key, ocrxxxx object status enum, REGSTATUS macro 
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aspectdocprint registration key 


aspectdocprint registration key 


Registers option flags that affect the printed document view of an object. The printed 
document view usually approximates how the object will appear if sent to the current 
printer. The option flags control how the docprint view is presented. 


Linking and embedding servers can optionally register aspect status in their document 
registration tables. Aspect status does not apply to application registration tables, 
containers, or automation servers. 


To register flags for the printed document aspect, use the REGSTATUS macro, passing 
"docprint” as the first parameter and an ocrxxxx object status enum value as the second 
parameter. 


See also 
aspectall registration key, aspectcontent registration key, aspecticon registration key, 
aspectthumbnail registration key, ocrxxxx object status enum, REGSTATUS macro 


aspecticon registration key 


Registers option flags that affect the iconic view of an object. The icon view, rather than 
showing the object's contents, displays an icon that represents a particular kind of object. 
The option flags control how the icon view is presented. 


Linking and embedding servers can optionally register aspect status in their document 
registration tables. Aspect status does not apply to application registration tables, 
containers, or automation servers. 


To register flags for the icon aspect, use the REGSTATUS macro, passing "icon" as the 
first parameter and an ocrxxxx object status enum value as the second parameter. 


REGSTATUS (icon, ocrOnlyIconic) 


See also 
aspectall registration key, aspectcontent registration key, aspectdocprint registration 
key, aspectthumbnail registration key, ocrxxxx object status enum, REGSTATUS macro 


aspectthumbnail registration key 


Registers option flags that affect the thumbnail view of an object. The thumbnail view 
usually shows a miniature representation of the object's contents. The flags control how 
the thumbnail view is presented. 


Linking and embedding servers can optionally register aspect status in their document 
registration tables. Aspect status does not apply to application registration tables, 
containers, or automation servers. 
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To register flags for ihe thumbnail aspect, use the REGSTATUS macro, passing 
"thumbnail" as the first Paramcres and an ocrxxxx object status enum value as the second 
parameter. 


See also 
aspectall registration key, aspectcontent registration key, aspectdocprint registration 
key, aspecticon registration key, ocrxxxx object status enum, REGSTATUS macro 


An automation controller uses AUTOARGS to implement methods in its proxy objects. 
AUTOARGS macros list all the arguments that the controller passes to an automation 
command, identifying them by the dummy parameter names used in the function 
definition. 


AUTOARGS macros are the second in three sets of macros used to implement methods 
in proxy objects. The first, AUTONAMES assigns names to any arguments that the 
controller wants to reference by name. The third set, AUTOCALL, tells whether the 
command i is a method or a property and whether it returns a value. 


The automacr.h header defines AUTOARG macros that accept up to six arguments. To 
generate versions that accept more arguments, use the MACROGEN.EXE utility. 


4 oo 
/ AUTOARGSI (al) The automation command requires argument a1. 


AUTOARGSA2(al, a2) The automation command requires arguments a1 and a2. 
AUTOARGSS(al, a2, a3) The automation command requires arguments a1, a2, and a3. 
AUTOARGSA(a1, a2, a3, a4) The automation command requires arguments 41, a2, a3, and a4. 


AUTOCALL xommacros —__tiautomac.h 


AUTOCALL is the third of three sets of macros that an automation controller uses to 
implement automation commands in proxy objects. The first two sets, AUTONAMES 
and AUTOARGS, describe the command's arguments. AUTOCALL macros tell 
whether the command represents a method or a property of the automated object and 
whether the command returns a value. Commands whose return value is itself an 
automated object must also be specially marked. 


AUTOCALL_METHOD_REF(prx) |The command is a method that returns a reference to an object. prx is 
| an object derived from TAutoProxy and receives the return value. 


AUTOCALL_METHOD_RET The command is a method that returns a value. 

AUTOCALL_ METHOD_VOID The command is a method that returns no value. 

AUTOCALL_PROP_GET | The command returns the value of a property of the automated 
| object. 
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_AUTOCLASS macro 


: : Meaning — oa ease en oe 
AUTOCALL. PROP. "RER(pr) The command returns the pale of a hearer and the values is sitself 
an object. prx is an object derived from TAutoProxy and receives the 
return value. 
AUTOCALL_PROP_SET(val) The command assigns val to a property of the automated object. 
_AUTOCLASS macro ocf/autodefs.h 


_AUTOCLASS is the class modifier that ObjectComponents uses to declare the base 
classes and member objects it creates inside your classes for automation. As long as your 
own classes use the application's ambient memory model, you do not have to worry 
about _AUTOCLASS, which by default is defined as nothing. If, however, you declare 
your automation classes with a modifier that differs from the ambient class model, then 
the classes (such as TAutoBase) that ObjectComponents defines must be modified to 
match. To accomplish the modification, define AUTOCLASS yourself. For example: 


#define _AUTOCLASS _ far 


AUTODATAmacros Ss etfautomach 


An automation server uses AUTODATA macros in an automation declaration (after 
DECLARE_AUTOCLASS) to make data members of an automated class accessible 
through OLE. 


Both forms take the same four parameters. name is the internal name that you assign to 
the data member. ObjectComponents uses the internal names to keep track of all the 
automated members. The only other place you use this name is in the subsequent 
automation definition (after DEFINE_AUTOCLASS). 


member is the C++ name of the data member, the name you normally use in oo source 
code. 


In most cases, type should be a noeael C++ data type, but if the data member is a string 
or an object then specify TAutoString or one of the TAutoObject classes instead. See 
Automation Data Types for more details. 


options is a place to insert a hook, code to be called each time the automation command 
is executed. Hooks can record, undo, or validate commands. See Automation Hook 
Macros for more details. options can be omitted, but a comma must follow the preceding 
argument anyway. 


. AUTODATA(name, member, type, options) The command permits read and write access to a data 
member. 


AUTODATARO(name, member, type, options) The command permits read-only access to a data 
member. 
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AutoDataType enum 


AutoDataType enum 


enum AutoDataType 


ocflautodefs.h 7 


These flags identify automation data types. The types correspond to standard OLE 2 
data types. The TAutoVal class uses the flags to guide its conversions to and from the 


VARIANT unions that OLE passes between programs. 


atVoid void 

atNull SQL-style null 

atShort 2-byte signed int 

atLong 4-byte signed int 

atFloat 4-byte real | 

atDouble 8-byte real 

atCurrency currency 

atDatetime. datetime as double 

atString _ BSTR, string preceded by length 
atObject [Dispatch* 

atError SCODE 

atBool True = —1, false = 0 

atVariant VARIANT FAR* 

atUnknown = _[Unknown* 7 
atTypeMask _ Base type code without bit flags. 
atOLE2Mask Type code with bit flags. 


The preceding flags are mutually exclusive. A value can belong to only one type. Any of 
the type flags can, however, be combined with the following bit flags. 


My 


atEnum 


See also 


The value is a reference to an object. 


The value is an enumeration of some type. 


AUTODETACH macro 


TAutoVal class, TAutoEnumT public constructor | 


ocf/automacr.h 


AUTODETACH 

An automation server uses this macro in its automation declaration (after 

DECLARE _AUTOCLASS) to ensure that whenever the automated object is destroyed 
OLE receives notification. Sending the object's obituary to OLE prevents crashes should 
a controller attempt to manipulate the nonexistent object. The obituary is necessary only 
if the logic of your program makes it possible for the automated object to be destroyed 
by non-automated means while still connected to the controller. 
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AUTOENUM macros 


Deriving a class from TAutoBase serves exactly the same purpose. The advantage of 
AUTODETACH is that you can use it to automate classes you did not create and whose 
derivation you cannot control. 


An automation server uses the AUTOENUM macros to expose enumerated values to 
automation controllers. For example, if the server wants the controller to pass actions 
into a DoThis command, the server might create an enumerated type containing values 
such as Play, Stop, and Rewind. To make these values available to the controller, the 
server must create an AUTOENUM table. In this example, the table consists of three 
AUTOENUM macros, one for each enumerated value. 


DEFINE_AUTOENUM(TAction, TAutoShort) ; 
AUTOENUM("Play", Play) 
AUTOENUM("Stop", Stop) 
AUTOENUM("Rewind", Rewind); 

END_AUTOENUM(TAction, TAutoShort) 


DEFINE_AUTOENUM(cls, type) Begins an AUTOENUM table. cls is the name of the automated 
enumeration type (not the name of the C++ enumerated type). You 
invent this name. The only other place it appears is in the application's 
automation definition. 


type is the automation data type that describes what kind of values are 
being enumerated. For more information, see Automation Data 
Types. 


AUTOENUM(name, val) name is the public string that a controller uses to refer to one in a series 
of enumerated values. val is the internal value the server associates 
with name. 


END_AUTOENUM<(cls, type) Ends an AUTOENUM table. cls and type are the same as for 
DEFINE_AUTOENUM. 


AUTOFLAG macro tfautomach 


AUTOFLAG(name, data, mask, options) 
An automation server uses AUTOFLAG in an automation declaration (after 
DECLARE_AUTOCLASS) to expose for automation a single bit from a set of bit flags. 


name is an internal name that you assign to the bit. ObjectComponents uses the internal 
names to keep track of all the automated members. The only other place you use this 
name is in the subsequent automation definition (after DEFINE_AUTOCLASS.) 


data is the C++ name of a data member that holds a set of bit flags. 
mask is a value with one bit set marking the position of the exposed flag in data. 


options is a place to insert a hook, code to be called each time the automation command 
is executed. Hooks can record, undo, or validate commands. See Automation Hook 
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-AUTOFUNG macros. 


Macros for more details. ee can se omitted, but a comma must ee the sredeaiie 


3 argument ene: 


An automation server uses AUTOFUNC macros in an automation declaration (after 
DECLARE_AUTOCLASS) to make member functions of an automated class accessible 
through OLE. 


In every version of the macro the first parameter, name, is an internal name that you 
assign to the function. ObjectComponents uses the internal names to keep track of all the 
automated members. The only other place you use this name is in the subsequent 
automation definition (after DEFINE_AUTOCLASS). 


func is the C++ name of the member function, the name you normally use in your source 
code. , 


ret is the type of data the function returns. type1, t1, t2, 3, and t4 represent the data types 
of the parameters. In most cases, all these data types should be normal C++ data types, 
but if the data member is a string or an object then specify TAutoString or one of the 
TAutoObject classes instead. See Automation Data Types for more details. Also, 
automated functions cannot return const values. Do not use const in a ret type. 


_ options is a place to insert a hook, code to be called each time the automation command 
is executed. Hooks can record, undo, or validate commands. See Automation Hook 
Macros for more details. options can be omitted, but a comma must follow the preceding 
argument anyway. , 


The automacr.h header defines versions of this macro that accept up to three arguments. 
To generate versions that accept more arguments, use the MACROGEN.EXE utility. 


AUTOFUNCO(name, func, ret, options) _ The function takes no parameters and returns a 
value of type ret. 
AUTOFUNCOV(name, func, options) The function takes no parameters ea returns void. 
AUTOFUNCI1 (name, func, ret, type1, options) The function takes one parameter of type typel and 
| returns a value of type ret. 
~ AUTOFUNC1V(name, func, typel, options) The function takes one parameter of type typel and 
returns void. 
AUTOFUNC2(name, func, ret, t1, t2, options) The function takes two parameters of types ¢1 and 
| | 7 #2. It returns a value of type ret. 
AUTOFUNC2V(name, func, t1, 2, options) | The function takes two parameters and returns 
| void. 
AUTOFUNC3 (name, func, ret, t1, t2, t3, options) The function takes three parameters and returns a 
| , value. 
AUTOFUNC3V(name, func, t1 ,t2, t3, options) The function takes three parameters and returns 
: | void. 
-~ AUTOFUNC4(name, func, ret, t1, t2, t3, t4, options) The function takes four parameters and returns a 
| value. 
AUTOFUNC4V(name, func, t1, t2, 3, t4, options) The function takes four parameters and returns 
void. 
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AUTOINVOKE macro 


AUTOINVOKE macro tzutomacrh 


AUTOINVOKE (code) 

An automation server uses AUTOINVOKE in an automation declaration macro to hook 
in user-defined code for ObjectComponents to execute every time the application 
receives a particular automation command. code is the expression or function call to 
execute on each command. 


Create an AUTOINVOKE hook if you want to override the normal execution sequence. 


_ An iterator is an object used to enumerate a collection of objects. An iterator's methods 
let the caller step through a list of objects and examine each one in turn. 


An automation server needs to create an iterator in any automated object that represents 
a collection of other objects. To create an iterator, the server adds one of the 
AUTOITERATOR macros to the class's automation definition (after 
DEFINE_AUTOCLASS). The iterator must also be exposed in the automation definition 
with the EXPOSE_ITERATOR macro. 


AUTOITERATOR<tate, init, test, step, extract) Implements a collection iterator within the automated 
class. , 

AUTOITERATOR_DECLARE(state) Declares but does not implement a collection iterator 
within the automated class. Use this if your iterator's 
implementation is too complex for AUTOITERATOR. 


The five arguments of AUTOITERATOR define the iteration algorithm for the collection 
class. Only one auto-iterator can exist within a class, so there is no need for a special 
internal name. The five arguments each represent a code fragment, and they follow the 
sequence of code in a for loop. As the examples show, because the iterator object is 
nested within the automated collection class, it can refer to members of the class. 


oy ween ae : : 2 t a 
~ int Index -___Declaration of state variables. This must be the same declaration 
previously given in AUTOITERATOR_DECLARE. 
init Index = 0 Statements (usually assignments) executed to initialize the loop. 
test Index < This->Total Boolean expression tested each time through the loop. 
step Index++ Statements executed each time through the loop. 
extract (This->Array)[Index] | Expression that returns the successive objects in the collection. 


Within the parameters, This (note the capital T) points to the enclosing collection object, 
not to the nested iterator object. 


Commas cannot be used except inside parentheses. Semicolons can be used to separate 
multiple statements, but not to end a macro argument. 
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AUTONAMES macros 


~AUTONAMES macros 


If you use AUTOITERATOR_DECLARE instead of AUTOITERATOR, then you must 
implement the state variables and these methods, corresponding to the steps described 
for AUTOITERATOR. — 


void Init ( 
bool Test ( 
void Step ( 
void Retur 


f 


) 
le 
n(TAutoVal& v); 


ocf/automacr.h 


The AUTONAMES macros are the first in three sets of macros that an automation 
controller uses to implement methods in its proxy objects. AUTONAMES macros assign 
names to any arguments that the controller wants to reference by name. Named _ 
parameters have default values and are not required in a command. If a command has 
fifteen parameters and ten of them have names and default values, then the controller 
must always pass the five unnamed parameters and can choose to pass any subset of the 
remaining ten, identifying them by their names. 


The second set of macros, AUTOARGS, describe the data types of unnamed arguments 
that must always be passed in the command. The third set, AUTOCALL, tells whether 
the command is a method or a property and what it returns. 


In the macros that follow, id is a numeric ID for a method, fname is a string naming a 
method, and 11, n2,n3, and n4 are strings assigned as argument names. Most of the 
macros need the function name to identify the function, but if a function has no named 
arguments, then you can pass its identifying number instead. 


The automacr.h header defines AUTONAMES macros that accept up to ten arguments. 
To generate versions that accept more arguments, use the MACROGEN.EXE utility. 


AUTONAMESO(id) 
AUTONAMESO(fname) 
AUTONAMESI(fname, n1) 
AUTONAMES2 (fname, n1, n2) 
AUTONAMES3 (fname, n1, n2, n3) 


Function id has no named. arguments. 

Function fname has no named arguments. 

Function fname has one named argument, n1. 

Function fname has two named arguments, n1 and n2. 
Function fname has three named arguments, n1, 12, and n3. 


AUTONAMES4(fname, n1,n2,n3,n4) Function fname has four named arguments, n1, n2,n3, and n4. 


AUTONOHOOK macro 


AUTONOHOOK 


ocf/automacr.h 


An automation server uses AUTONOHOOK in an automation declaration macro to 
_ prevent anyone from hooking the command. Not even ObjectComponents can monitor 
the call. 


AUTONOHOOK is for advanced uses only. 
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AUTOPROP macros 


An automation server uses AUTOPROP macros in its automation declaration (after 
DECLARE _ AUTOCLASS) to make properties of an automated class accessible to OLE. 
A property is data that cannot be read or written directly, only through a set of access 
functions (for example, GetPosition and SetPosition). 


A server can implement the access functions any way it likes. Because only the access. 
functions are exposed, the property does not have to be a data member. In other words, 
GetPosition and SetPosition would not have to refer to a data member of type TPoint. 
They might query the system for the cursor position and return the answer. 


The three AUTOPROP macros have similar parameters. name is an internal name you 
assign to the property. ObjectComponents uses the name to keep track of all the 
automated members. The only other place you use this internal name is in the 
corresponding automation definition. 


get and set are the access functions. A read-only property has just a get function. A write- 
only property has just a set function. 


type is the property's data type. This is usually a C++ data type, but string and object 
properties require special treatment. See Automation Data Types for more information. 


options is a place to insert a hook, code to be called each time the automation command 
is executed. Hooks can record, undo, or validate commands. See Automation Hook 
Macros for more details. options can be omitted, but a comma must follow the preceding 
argument anyway. 


| AUTOPROP(name, get, set, type, options) The property canbe read and written. 
AUTOPROPRO(name, get, type, options) The property can only be read, not changed. 
AUTOPROPWOv(name, set, type, options) The property can be changed but not read (rare). 


AUTORECORD macro = ttautomacr.h 


AUTORECORD (code) 

An automation server uses AUTORECORD in an automation declaration macro to hook 
in user-defined code that creates a record of each call made to a particular automation 
command. code is the expression or function call to execute on each command. It should 
store whatever information the application would need to play back the same command 
later. | 


Recording is not supported in the current version of ObjectComponents. 


AUTOREPORT(code) 
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AutoSymFlag enum 


An automation server uses AUTOREPORT in an automation declaration macro to hook 
in user-defined code that checks the error code from an automated member function. If 
code evaluates to 0, OLE assumes the command succeeded. If code evaluates to a nonzero 
value, then OLE throws an exception in the controller. Within the code Spe use 
Val to refer to the actual value returned. 


enum AutoSymFlag 

' These flags are used in the TAutoCommand class to describe attributes of an automation 
command. The flags tell whether the command is a method or a property, whether 
arguments are passed by value or by reference, and whether it should be visible in type 
information browsers. 


asAnyCommand Any command: method, property access, object builder. 


asOleType Method or property exposed for OLE. 

asMethod Method. 

asGet Returns the value of a property. 

aslterator Iterator property; used to enumerate items in a collection. 
asset Set property value. 

asGetSet Get or set a property value. 

asBuild Constructor command (not supported by OLE 2.01). 
asArgument Property that returns an object. 

asArgByVal The value of the argument is passed. 

asArgByRef The argument is a pointer to a value. 

asFactory For creating objects or determining class. 

asClass Extension to another class symbol table. 

asBindable Sends OnChanged notification. 


asRequestEdit Sends OnRequest edit before change. 
asDisplayBind User-display of bindable. — 
asDefaultBind This property only is the default (redundant). 


asHidden Not visible to normal browsing. 
asPersistent Property is persistent. 
See also 


TAutoCommand public constructor 


Use the AUTOSTAT in an automation declaration (after DECLARE_AUTOCLASS) to 
make static member functions and global functions accessible to OLE. 
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AUTOTHIS macro 


All versions of the AUTOSTAT macro have similar parameters. name is an internal 
name you assign to the function. ObjectComponents uses the name to keep track of all 
the automated members. The only other place you use this internal name is in the 
corresponding automation definition. 


func is the name of the static or global function. 
ret is the type of value the function returns. 
typel, t1, t2, t3, and 4 are the types of the function's arguments. 


options is a place to insert a hook, code to be called each time the automation command 
is executed. Hooks can record, undo, or validate commands. See Automation Hook 
Macros for more details. options can be omitted, but a comma must follow the preceding 


argument anyway. 
The return types and argument types are usually normal C++ data types, but string and 
object values require special treatment. See Automation Data Types for more 


information. 

AUTOSTATO(name, func, ret, options) _ The static function func is assigned the symbol name. 
It takes no arguments and returns a value of type ret. 

AUTOSTATOV(name, func, options) The static function func takes no arguments and 
returns no value. 

AUTOSTAT1 (name, func, ret, typel, options) func takes one argument of type typel and returns a 
value of type ret. 

AUTOSTAT1V(name, func, typel, options) func takes one argument of type typel and returns no 
value. 

AUTOSTAT2(name, func, ret, t1, t2, options) func takes two et aie of types t1 and #2 and 
returns a value of type ret. 

AUTOSTAT2V(name, func, t1,t2, options) func takes two arguments and returns no value. 

AUTOSTAT3 (name, func, ret, t1,t2, t3, options) func takes three arguments and returns a value. 

AUTOSTAT3V(name, func, t1, t2, t3, options) func takes three arguments and returns no value. 


AUTOSTAT4(name, func, ret, t1, t2, t3, 4, options) func takes four arguments and returns a value. 
AUTOSTAT4V(name, func, t1, t2, t3, t4, options) func takes four arguments and returns no value. 


AUTOTHISmacro__tautomach 


AUTOTHIS(name, type, options) 

An automation server uses the AUTOTHIS macro in its automation declaration (after 
DECLARE AUTOCLASS) if it wants to expose the C++ object itself as a member of the 
automated OLE object. 


name is an internal name you assign to the property. ObjectComponents uses the name 
to keep track of all the automated members. The only other place you use this internal 
name is in the corresponding automation definition. 


type must be TAutoObject<T>, where T is the type of the automated class. 
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AUTOUNDO macro 


options is a place to insert a hook, code to be called each time a controller asks for this 
property. Hooks can record, undo, or validate commands. See Automation Hook 
Macros for more details. options can be omitted, but a comma must follow the preceding 
argument anyway. 


ee 


AUTOUNDO (code) 

An automation server uses AUTOUNDO in an automation declaration macro to hook 
in user-defined code that records whatever information the application needs to reverse 
the command later. Usually it adds information to a user-maintained undo stack. The 
information might include the parameters that execute the inverse of the original 
command, for example. To undo a series of actions, the program can pop commands off 
the undo stack and execute them. code is the expression or function that records 
information. 


Undoing commands is not supported in the current version of ObjectComponents. 


AUTOVALIDATE macro __ctautomacrh 


~ AUTOVALIDATE(condition) 
An automation server uses AUTOVALIDATE in an automation declaration macro to 
hook in user-defined code that confirms the validity of received arguments before 
passing them on to be processed in a command. condition is an expression or function 
that evaluates to true if the arguments received are valid for the command and false if 
not. If the expression returns false, OLE throws an exception in the controller 
: application. 


cisid registration key 


Registers a globally unique identifier (GUID) for the spplcKion s class ID. A GUID is a 
16-byte value and can be represented as a string. | 


A clsid GUID is required in every application registration table. You never need to 
specify any others. If others are needed for your documents, type library, automated 
classes, or debugging invocation, ObjectComponents automatically increments the low- 
order field of the first GUID to produce them. Be sure to allow for the full range of 
numbers your application actually uses when determining the next available GUID for 
another program. 


There are several ways to acquire a clsid. One is to run the GUIDGEN tool in the 
OCTOOLS directory. Also, AppExpert automatically generates a GUID for any 
applications it creates that support OLE. Another way to get a GUID is to call the OLE 
API CoCreateGuid, as documented in the Help file OLE2HELP.HLP. Finally, you can 
contact Microsoft to have a block of GUIDs assigned to you permanently. 
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cmdline registration key 
Every application must have its own absolutely unique clsid string, so never use values 
pasted in from example programs. 


To register a clsid, use the REGDATA macro with clsid as the first parameter and a GUID 
string as the second parameter. 


REGDATA(clsid, "{CDE7F941-544B-101B-A9C1-04021C007002}") 


cmdline registration key 


Registers arguments OLE should place on the command line when it launches the 
server's executable file. 


The cmdline key is valid in application registration tables but is ignored for DLL servers. 
Any application can register it, but normally only automation servers have a use for it. 


Automation servers can use the cmdline key to set up the —Automation switch. When the 
registrar object sees this switch, it overrides the application's registered usage setting and 
forces the program to run in single-use mode. This is useful in a server that supports 
linking and embedding as well as automation. As a linking and embedding server, it 
might support concurrent client applications with a single instance. When running as an 
automation server, however, most applications don't want concurrent client programs 
to control exactly the same instance of an object. 


To register command-line options, use the REGDATA macro with cmdline as the first 
parameter and a string containing command-line arguments as the second parameter. 


REGDATA(cmdline, "/automation") 


A GUID identifying the debugging version of a server. You should never register this 
key directly. It is always generated for you automatically if you register debugprogid. 


This key is ignored in DLL servers. 


See also 
debugprogid registration key 


debugdesc registration key 


A string describing the debugging version of your program. When used in registering a 
document, this string appears in the Insert Object menu. When used in registering an 
application, it appears in object browsers. The string can contain up to 40 characters and 
can be localized. 


The debugdesc key is required in application and document registration tables for any 
program that registers the debugprogid key. Otherwise it is irrelevant. 
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neu g ae cearsieation key 


To register the debugdesc key, use the REGDATA macro, passing as as ; the first 
parameter and the descriptive string as the second Peomet 


REGDATA (debugdesc, "My Application. (debugging) ") 


This key is ignored in DLL servers. 


See Also” 
debugclsid registration key, ae registration key, debugprogid registration key, 
REGDATA macro 


debugger registration key 


Registers the path and file name for loading your debugger. 


The debugger key is valid in any registration table. It is required if you also register 
debugprogid. Otherwise it is irrelevant. | 


To register the debugger key, use the REGDATA macro, passing debugger as the first 
parameter and the command line string for the debugger application as the second 
parameter. When OLE invokes the debugger, it places the second parameter string on 
the command line ahead of the server's .EXE path. The debugger string can eipnnry 
contain a full path and debugger command line switches. | 


REGDATA (debugger, "TDW") // assumes TDW is somewhere on the path 


This key is ignored in DLL servers. 


See also 
debugclsid registration hey debugdesc registration key, debugprogid registration key, 
REGDATA macro 


debugprogid registration key 


A string identifying the debugging version of a program. Just as a progid string does, this 
string has two parts divided by a period. The first part is your program’s name, and the 
second part is .debug. 


Assigning a value to the debugprogid key causes ObjectComponents to create two sets of 
entries for the server in the registration database. When you choose Insert Object from 
the Edit menu, both entries appear in the list. Choosing the debugging entry causes 
ObjectComponents to invoke your debugger together with the server. Without the 
ability to register a duplicate debugging as it is > difficult to debug the server when 
OLE invokes it. | 


ObjectComponents generates a clsid for the debugger entry automatically. 


The debugprogid key is optional for application registration tables and irrelevant for 
document registration tables. If you register debugprogid, you also need to register 
debugdesc and debugger. | . : 
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DECLARE AUTOCLASS macro 


To register a debugprogid, use the REGDATA macro, passing debugprogid as the first 
parameter and the ID string as the second parameter. 


REGDATA(debugprogid, "MyApp.Debug") 


This key is ignored in DLL servers. 


See also 
debugclsid registration key, debugdesc registration key, debugger registration key, 
progid registration key, REGDATA macro 


a St 


DECLARE AUTOCLASS(cls) 
DECLARE _AUTOCLASS (cls) introduces a block of macros that declare automatable 
members of the user-defined class cls. 


An automation server uses DECLARE_AUTOCLASS to begin a block of macros that 
make automatable members of a user-defined C++ class accessible to OLE. cls is the 
name of the user's C++ class. 


The block of declaration macros usually appears in the definition of the automatable 
C++ class. A corresponding block of automation definition macros must appear in the 
implementation of the automatable C++ class. 


Use the COMBASES macros to create C++ objects that conform to the OLE Component 
Object Model (COM). COM objects support OLE interfaces and let you derive classes 
that interact with OLE directly, not through ObjectComponents. These macros are 
meant for advanced users. 


COM objects are used as base classes for other objects. The derived class must inherit 
from both your COM class and from the ObjectComponents TUnknown class. TUnknown 
implements the controlling [Unknown interface for your object. 


To create a COM class: 


1 Precede the declaration of the class with one of the DECLARE COMBASES macros. 
Which you choose depends on how many interfaces (besides [Unknown) the COM 
class supports. 


2 Precede the implementation of your COM class with the corresponding 
DEFINE _COMBASES macro. 


3 Derive your final class multiply from TUnknown and your new COM class (in that 
order). | 
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DEFINE_AUTOAGGREGATE macro 


The first macro argument is name. It is the name of the COM class you are creating. 11, 12, | 
_ 13, and 74 are the names of the interfaces your COM class supports. 


class. » 


DECLARE COMBASES2(name, i1, i2) Declare a COM class name that inherits ae the 11 and 12 
interface classes. 


DECLARE COMBASES3(name, i1, i2, 13) Declare a COM class name that inherits from the 71. i2, and 
13 interface classes. 


DECLARE _COMBASESA(name, i1, i2, 13,14) Declare a COM class name that ceri from the 71. i2, i3, 
and 74 interface classes. 


DEFINE AUTOAGGREGATE(cls, AggregatorFunction) 

An automation server uses DEFINE _AUTOAGGREGATE to begin a block of macros 
that define automatable members of cls, a user-defined C++ class. The block ends with 
the END_-AUTOAGGREGATE macro. 


DEFINE_AUTOCLASS does the same thing but without the extra AggregatorFunction 
parameter. Use DEFINE _AUTOAGGREGATE when the C++ class you are automating 
is, inherits from, or delegates to a Component Object Model (COM) object. The 
AggregatorFunction parameter points to the aggregating function for reaching the COM 
object. For example, if Aggregate is the name of the COM object, the aggregater function 
might be any of these expressions: | 


Aggregate // automated C++ object is the COM object 
OcApp->Aggregate // automated C++ object delegates to COM object 
MyBase::Aggregate // automated C++ object inherits from COM object 


See also 
DEFINE_AUTOCLASS, END_AUTOAGGREGATE 


DEFINE _AUTOCLASS macro ttautomacr.h 


DEFINE AUTOCLASS(cls) 
Introduces a block of macros in an automation server. Each macro in the block defines 
an automatable member of cls, a user-defined C++ class. ‘The block ne with the 
END_AUTOCLASS macro. 


_ The block of definition macros appears in the implementation of the automatable C++ 
class. A corresponding block of automation declaration macros must appear in the 
definition of the same class. 


See also 
» END_AUTOCLASS macro 
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DEFINE COMBASESn macros 
DEFINE COMBASESn macros ocfloleutil.h 


Implements the [Unknown interface for each of the OLE interfaces that your COM object 
supports. 


Use the COMBASE macros to create C++ objects that conform to the OLE Component 
Object Model (COM). COM objects support OLE interfaces and let you derive classes 
that interact with OLE directly, not through ObjectComponents. These macros are 
meant for advanced users. 


Automated objects can delegate to COM objects using the 
DEFINE AUTOAGGREGATE and DECLARE_AUTOAGGREGATE macros. 


To create a COM class, 


1 Precede the declaration of the class with one of the DECLARE COMBASES macros. 
Which you choose depends on how many interfaces (besides [Unknown) the COM 
class supports. 


2 Precede the implementation of your COM class with the corresponding 
DEFINE_COMBASES macro. 


3 Derive your final class multiply from your new COM class and from TUnknown. 


COM objects can delegate to other COM objects using another set of related macros also 
defined in oleutil.h. For more information, look in the header file for the 
DEFINE_QOI xxxx macros. 


Macro ee a ee . - Meaning — ee . 

DEFINE “COMBASES1(name, i) Define I pee for the i pavnaraety in te COM Aer name. 

DEFINE_COMBASES2(name, il, 12) Define [Unknown for the 11 and 72 interfaces in the COM class 
name. 

DEFINE_COMBASES3(name, i1, 12, 13) Define [Unknown for the 11, i2, and 13 interfaces in the COM 
class name. 

DEFINE_COMBASESA4(name, il, 12, 13,14) | Define [Unknown for the 11, 12, 13, and i4 interfaces in the COM 
class name. 

See also 


DECLARE COMBASESn macros 


Registers a long descriptive name, up to 40 characters, meant for the user to see. The 
string describes the application or its document types and appears in the Insert Object 
dialog box. This value should be localized. 


A description string is required in every registration table. To register a description 
string, use the REGDATA macro, passing description as the first parameter and the 
descriptive string as the second parameter. 


REGDATA (description, "OWL Drawing Pad 2.0") 
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directory registration key 


See also 
REGDATA macro 


directory registration key 


Registers the default directory for document files. The document template class refers to 
this path when it invokes a File Open common dialog box. The directory path is not 
cused by OLE. | 


The directory key is valid in any document registration table. It is always optional. 


To register a directory, use the REGDATA macro, passing directory as the first parameter 
and a path name as the second parameter. 


REGDATA(directory, "C:\\temp") 


docfilter registration key 


Registers a file specification for listing files created by the application. This information — 
is used by the document template class when it creates a File Open common dialog box. 
It is not used by OLE. 


docfilter is valid in any document registration table. It is required unless the 
_ corresponding docflags key includes the dtHidden flag. If you register a document filter, 
you might also want to register the extension key. 


To register a document filter, use the REGDATA macro, passing docflags as the first 
parameter and a filter string as the second parameter. 


REGDATA(docfilter, "*.txt") 


See also | 
docflags registration key, dt document view constants, extension registration key, 
REGDATA macro 


docflags registration key 


Registers document view option flags for the application's documents. This information 

_ is used by the document template class, not by OLE. The document template uses the 
flags to control its display of the File Open common dialog box. For a list of all the flags, 
see the description of dtxxxx Document View Constants. 


The docflags key is valid in any document registration table. It is always optional. 
To register document flags, use the REGDOCFLAGS macro. 
REGDOCFLAGS (dtAutoOpen | dtAutoDelete | dtUpdateDir | dtCreatePrompt) 
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DynamicCast function 


See also 
docfilter registration key, dt document view constants, REGDOCFLAGS macro 


const void far* DynamicCast(const void far* obj, const typeinfo& src, const typeinfo& dst); 
Attempts to convert a pointer from one type to another. The attempt succeeds only if the 
old type and the new type are related through inheritance. 


obj is the pointer you want to cast to a new type. src is type information about the source 
object. dst is information about the destination type. 

If the conversion succeeds, DynamicCast returns a pointer to the new type. If it fails, the 
return is zero. 


You can generate the src and dst parameters with the typeid parameter. 
(ObjectComponents requires the use of RTTTL) 


See also 
MostDerived function, typeid, typeinfo class 


pee eneee Oe 


END AUTOAGGREGATE(cls, name, doc, help) 
Terminates a block of macros that an automation server uses to define automatable 


methods in cls, a user-defined C++ class. The definition block begins with 
DEFINE_AUTOAGGREGATE. 


The related DEFINE AUTOCLASS and END _AUTOCLASS macros also mark an 
automation definition block. Use the aggregation macros when cls is, inherits from, or 
delegates to a Component Object Model (COM) object. 


name is the string that automation controllers use to identify objects of type cls. If the 
user asks OLE about the object name, the system returns the string in doc. If an .HLP file — 
is registered for the object, then the context ID in help points to a screen that describes the 
object. 


See also 
DEFINE AUTOAGGREGATE macro, END _AUTOCLASS macro 


END AUTOCLASS(cls, name, doc, help) 
Terminates the block of macros an automation server uses to define automatable 


methods in cls, a user-defined C++ class. The definition block begins with 
DEFINE_AUTOCLASS. 
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EXPOSE APPLICATION macro 


name is the string that automation controllers use to identify objects of type cls. If the 
user asks OLE about the object name, the system returns the string in doc. If an .HLP file — 
is registered for the object, then the context ID in help points to a screen that describes the 
object. 


See also 
DEFINE AUTOCLASS macro 


EXPOSE_APPLICATION(cls, extName, doc, help) 
An automation server uses EXPOSE_APPLICATION in its automation definition (after 
DEFINE_AUTOCLASS) if it chooses to expose the application itself as a member of its 

_ automated object. OLE conventions suggest that each automation object should have 
this member. 


cls is the class name of the application. 


extName is the external, public name you assign to this member. Automation controllers 
use this string to refer to the application member. The string can be localized. 


doc is a string that describes this member to the user. An automation controller can ask 
OLE for this string if the user requests help. 


help is a context ID for an .HLP file. This parameter, which can be omitted, is useful only 
if you register an .HLP file to document your server. If you do, then when the user asks 
the controller for help, the controller passes this context ID to the Help system to display 
a screen describing the object member. 


EXPOSE_DELEGATE macro] = __octfautomaceh 


EXPOSE DELEGATE(cls, extName, locator) 
An automation server uses EXPOSE_ DELEGATE in its automation definition (after 

~ DEFINE_AUTOCLASS) in order to combine two unrelated C++ classes into a single 
OLE automation object. In effect, the application's primary automated class delegates 
some tasks to another automated class. This macro tells ObjectComponents to search 
both classes to determine what commands the automated OLE object can perform. 


cls is the name of the auxiliary class, which must also be automated. In other words, it 
must contain its own automation declaration and definition. 


extName is an external, public name that an OLE controller uses to refer to this member 
of the object. 


locator is a function that returns a pointer to an auxiliary object. In order to call members 
of that class, ObjectComponents needs a pointer to an object of that type. The conversion 
function should follow this prototype: 


auxclass *locator( autoclass *this ); 
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EXPOSE_INHERIT macro 


where auxclass is the name of the auxiliary class and autoclass is the name of the primary 
automated class. locator in effect converts a this pointer to a that pointer. 


See also 
EXPOSE_INHERIT macro 


EXPOSE_INHERITmacro = _etfautomacr.h 


EXPOSE_INHERIT(cls, extName); 

An automation server uses EXPOSE_INHERIT in its automation definition (after 
DEFINE_AUTOCLASS) in order to combine two related C++ classes into a single OLE 
automation object. In effect, the application's primary automated class delegates some 
tasks to its base class. This macro tells ObjectComponents to search both classes to 
determine what commands the automated OLE object can perform. 


cls is the name of the base class, which must also be automated. In other words, it must 
contain its own automation declaration and definition. 


extName is an external, public name that an OLE controller uses to refer to this member 
of the object. It can be localized. 


See also 
EXPOSE_DELEGATE macro 


EXPOSE_ITERATOR(retType, doc, help); 

An automation server uses EXPOSE_ITERATOR in its automation definition (after 
DEFINE_AUTOCLASS) in order to expose an iterator object to enumerate objects in a 
collection. An iterator is useful only when the automated object itself represents a 
collection of other objects. The controller uses methods of the nested iterator object to 
retrieve and examine successive objects in a list. 


retType is an automated data type that describes the type of the objects in the collection. 
For example, if the collection is an array of short integers, then retT ype should be 
TAutoShort. For more information, see Automation Data Types. 


doc is a string that describes the iterator to the user. An automation controller can ask 
OLE for this string if the user requests help. 


help is a context ID for an .HLP file. This parameter, which can be omitted, is useful only 
if you register an .HLP file to document your server. If you do, then when the user asks 
the controller for help, the controller passes this context ID to the Help system to display 
a screen describing the iterator. 


See also 
AUTOITERATOR macros 
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-EXPOSE_METHOD macros en oe Sy a FG | 
EXPOSE _ METHOD macros ; | ~ ocflautomacr.h 


EXPOSE _METHOD(intName, retType, extName, doc, help); 

EXPOSE METHOD ID(id, intName, retType, extName, doc, help); 

An automation server uses EXPOSE_METHOD macros in its automation definition 
(after DEFINE _AUTOCLASS) to expose a member function of an object to OLE for — 
automation. 


intName is an internal name that you assign to identify the method. ObjectComponents 
uses the internal name to keep track of all the automated members. This name must 
match the name apeleres to the method with the AUTOFUNC macro in the automation 
declaration. 


retType i is a data type that describes the type of value the method returns. For example, if 
the method returns a long integer, then retType should be TAutoLong. For more 
_ information, see Automation Data Types. © 


extName is the external, public name that a controller uses to specify this method. The 
string can be localized. . 


doc is a string that describes this adthiod to the user. An automation erates can ask 
OLE for this string if the user requests help. This string can also be localized. 


help is a context ID for an .HLP file. This parameter, which can be omitted, is useful only 

— if you register an .HLP file to document your server. If you do, then when the user asks 
the controller for help, the controller passes this context ID to the Help system to display 
a screen describing the method. 


id is a dispatch identifier that you can choose to assign explicitly by using one of the 
EXPOSE_METHOD_ID macros. The dispatch ID is what OLE passes to identify 
commands requested by a controller. The OLE system header files define several 
standard dispatch ID values. For example, —5 is the default evaluation method. Standard 
dispatch IDs are always negative numbers. By default, dispatch IDs are assigned low 
positive numbers incremented from 1. If you want to specify explicit dispatch IDs for 
your applications, choose high positive values in order not to collide with the low 
positive numbers ObjectComponents assigns to exposed members without explicit IDs. 


0 is the ID of the default method or property. ObjectComponents never automatically 
assigns 0 as a dispatch ID. To have a default method, you need to assign 0 yourself. 


An EXPOSE_METHOD or EXPOSE_METHOD_ID macro must always be followed 
immediately by one macro for each of the method's arguments. 


eq = 
Optional OPTIONAL_ARG 


Object ss by reference REQBYREF_ARG | 


See also 
AUTOFUNC macros, OPTIONAL “ARG macro, REQBYREF_ARG macro, — 
REQUIRED_ARG macro | 
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EXPOSE PROPxxxx macros 


An automation server uses EXPOSE_PROPxxxx macros in its automation definition 
(after DEFINE_AUTOCLASS) to expose properties of an object to OLE for automation. 
A property is data that can be read or written only through a set of access functions (for 
example, GetPosition and SetPosition). 


intName is an internal name that you assign to identify the property. ObjectComponents 
uses the internal name to keep track of all the automated members. This name must 
match the name assigned to the method with the AUTOPROP macro in the automation 
declaration. 


type is a data type that describes the type of value the property holds. For example, if the 
property is a string, then type should be TAutoString. For more information, see 
Automation Data Types. 


extName is the public name that a controller uses to refer to this property. The string can 
be localized. 7 


doc is a string that describes this property to the user. An automation controller can ask 
OLE for this string if the user requests help. This string can also be localized. 


help is a context ID for an .HLP file. This parameter, which can be omitted, is useful only 
if you register an .HLP file to document your server. If you do, then when the user asks 
the controller for help, the controller passes this context ID to the Help system to display 
a screen describing the property. 


id is a dispatch identifier that you can choose to assign explicitly by using one of the 
EXPOSE_xxxx_ID macros. The dispatch ID is what OLE passes to identify commands 
requested by a controller. The OLE system header files define several standard dispatch 
ID values. For example, —5 is the default evaluation method. Standard dispatch IDs are 
always negative numbers. By default, dispatch IDs are assigned low positive numbers 
incremented from 1. If you want to specify explicit dispatch IDs for your applications, 
choose high positive values in order not to collide with the low positive numbers 
ObjectComponents assigns to exposed members without explicit IDs. 


0 is the ID of the default method or property. ObjectComponents never automatically 
assigns 0 as a dispatch ID. To have a default property, you need to assign 0 yourself. 


EXPOSE_PROPRW(intN ame, type, extName, doc, help) - The property can be read and written. _ 
EXPOSE_PROPRW_ID(id, intName, type, extName, doc, help) The property can be read and written. 
| Its dispatch ID is id. 

EXPOSE_PROPRO(intName, type, extName, doc, help) The property is read-only. 
EXPOSE_PROPRO_ID(id, intName, type, extName, doc, help) The property is read-only. Its dispatch 

ID is id. 
EXPOSE_PROPWO(intName, type, extName, doc, help) The property is write-only and cannot 

be read (rarely used). 
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EXPOSE _QUIT macro 


EXPOSE _QUIT(extName, docString, helpContext) 
An automation server that exposes the application itself as an automated object uses the 
EXPOSE_QUIT macro to make a safe shutdown method available to the controller. The 
_ shutdown method implemented by this macro checks whether the application was 
originally invoked by OLE for automation. If so, it unregisters the active object and 
shuts down the server. If the user invoked the server before the controller connected to 
it, however, then the shutdown method does nothing because the application should 
continue to run. 


Every automated application should include EXPOSE_QUIT in the application object’ S 
automation definition (after DEFINE_AUTOCLASS). EXPOSE_QUIT is not needed in 
the automation definition of other automated objects the server might create. 


extName is the external, public name that a controller uses to call this method. The string 
can be localized. 


doc is a string that describes the shutdown method to the user. An automation controller 
can ask OLE for this string if the user requests help. This string can also be localized. 


help is a context ID for an .HLP file. This parameter, which can be omitted, is useful only 
if you register an .HLP file to document your server. If you do, then when the user asks 
the controller for help, the controller passes this context ID to the Help ee to display 
a screen describing the shutdown method. 


extension registration key 


A file-name extension. This extension becomes the default extension assigned to file 
names in the File Open common dialog box. It is also recorded in the system registration 
database so that OLE can find the right server for a file based on the file's extension. 


extension is valid in document registration tables of servers that support linking and 
embedding. It is always optional. If you register an extension, you might also want to 
register a docfilter. 


To register a file extension, use the REGDATA macro, passing extension as the first _ 
parameter and the extension string as the second parameter. In 16-bit Windows, the 
extension is limited to three characters. 


REGDATA(extension, "TXT") 


See also 
docfilter registration key, REGDATA macro 
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filefmt registration key 


filefmt registration key 


_ Registers a name for a server’s default file format. This string appears in dialog boxes 
where the user selects file types. 


filefmt is valid in document registration tables for servers that support linking and 
embedding. It is always optional. 


To register a file format, use the REGDATA macro, passing filefmt as the first parameter 
and the name string as the second parameter. 


See also 
REGDATA macro 


formatn registration key 


Registers a Clipboard format the application supports. An application registers the 
formats that it can put on or take from the Clipboard. A server can register different sets 
of formats for different document types. 


Clipboard format keys are valid in any document registration table. Any application 
that supports linking and embedding should register at least some Clipboard formats. 
ObjectComponents supports up to eight formats using the keys format0 through format7. 
The ocrFormatLimit constant, defined in ocf/ocreg.h, represents the maximum number 
of formats allowed (8). 


To register a Clipboard format, use the REGFORMAT macro. The first parameter 
assigns a priority to the format. Give your preferred format highest priority. Programs 
that support OLE usually prefer to export their data as OLE objects, and so they make 
ocrEmbedSource priority 0. The second parameter identifies a particular data format. For 
explanations of the other parameters, see the description of the REGFORMAT macro. 


REGFORMAT(0, ocrEmbedSource, ocrContent, ocrIStorage, ocrGet) 
REGFORMAT(1, ocrMetafilePict, ocrContent, ocrMfPict, ocrGet) 


See also 
OCrxxxx aspect constants, ocrxxxx Clipboard constants, ocrxxxx direction constants, 
ocrxxxx medium constants, REGFORMAT macro 


handler registration key 


A full path pointing to a library that can draw objects created by the server. 


A path for the library that OLE can call to draw objects without having to launch the 
server as a separate process. By default this value is "OLE2.DLL." OLE itself can render 
cached formats such as metafiles and bitmaps. 
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helpdir registration key. 


The handler key is valid in document eoeeton tables for servers that support linking 
and embedding. It is always optional, but if you omit it OLE cannot use your handler 
library. | 


To register a handler, use the REGDATA macro passing handler as the first parameter 
and the path of the handler DLL in the second parameter. If the path does not begin 
with a drive or root directory, ObjectComponents determines the full path by starting at 
the place where the server itself is installed. For example, if the server is at C:\MYDIR 
and the handler path is HELPERS\MYHANDLR, then the full path is assumed to be 
C:\MYDIR\HELPERS\MYHANDLR.DLL. 


See also 
REGDATA macro 


helpdir registration key 


Directory where online Help for the type library resides. (The name of the Help file is 
registered separately with the typehelp key.) 


This key matters only in the application registration table of an automation controller. It 
is always optional. If you register a type library Help file without registering a Help 
directory, ObjectComponents automatically assumes the same directory registered for 
path. 


To register a Help directory, use the REGDATA macro passing helpdir as the first 
parameter and the path string as the second parameter. 


If the path does not begin with a drive or root directory, ObjectComponents determines 
the full path by starting at the place where the server itself is installed. For example, if 
the server is at C:\MYDIR and the Help path is HELP, then the Help file is assumed to 
be at C:\MYDIR\HELP. 


See also 
path registration key, typehelp registration key 


HR_xxxx return constants ocflocfdefs.h 


OLE system calls return HRESULT values that sometimes encode detailed information 
about the result of the call. ObjectComponents sometimes passes HRESULT values back 
to you. These macros simplify the task of testing for some common results. Each 
represents a possible return value. For a complete listing of HRESULT return values, see 
the scode.h header file. 


& e operation was aborted. 
HR_FAIL An unspecified error occurred. 
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iconindex registration key 


nstant Meaning — | | | 

HR_FALSE | An action did not complete i in the ‘sual way eh no error occured For eamhple, 
an enumeration reached the end of its list. 

HR HANDLE A handle is invalid. 

HR_INVALIDARG One or more arguments are invalid. 

HR_NOERROR No error occurred. 

HR_NOINTERFACE _ The requested interface is not supported. 

HR_NOTIMPL The requested service is not implemented. 

HR_OK Same as HR_NOERROR. 

HR_OUTOFMEMORY _ Not enough memory is available to complete the operation. 

HR_POINTER A pointer is invalid. 


iconindex registration key 


A zero-based index telling which of the icons in the server's resources represents the 
type of objects the server produces. 


Use iconindex in the document registration tables of a linking and pReceans server. It is 
always optional. 


To register an icon index, use the REGICON macro, passing the index value as the 
parameter. 


REGICON (1) 


See also 
REGICON macro 


insertable registration key 


Indicates the application is a server and allows its document to be linked or embedded 
in other applications. Registering this key makes the document type show up in dialog 
boxes listing objects that can be inserted. The value assigned to this key is ignored. 


insertable is valid in the document registration tables of a linking and embedding server. 
An application must register insertable for at least one document type in order to be a 
linking and embedding server. A server need not make all its document types 
insertable, however. 


To register the insertable key, use the REGDATA macro, passing insertable as the first 
parameter and 0 as the second parameter. 


REGDATA (insertable, 0) 


See also 
REGDATA macro 
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language logistr alien key 
language registration key 


Overrides the locale ID currently in effect. By default, the language key takes its value 
from the system's default language setting for the current user. Registering a language 
setting directs ObjectComponents to choose a particular language for registration | 
strings you have localized. 


During automation this value is reset internally at the request of the automation 
controller. | 


menuname registration key 


A short name for the server. The name appears as a menu item in container programs. 
For consistency in the user interface, the suggested maximum length is 15 characters. 


menuname is required in the document registration tables of a linking and embedding 
server. In other places it is irrelevant. The menuname string can be localized. 


To register the menuname key, use the REGDATA macro, passing menuname as the first 
parameter and a name string as the second parameter. 


REGDATA(menuname, "OWL Drawing Pad") 


See also 
REGDATA macro 


MostDerived function | ocf/autodefs.h 


const void far* MostDerived(const void far* obj, const typeinfo& src); 

Returns a pointer to the most derived class type that fits the given object. This is useful 
when dealing with polymorphic objects. Use it to obtain a consistent pointer to an 
object, regardless of the type of pointer used to reach the object. 


obj is the pointer whose most derived type you want to determine. src holds type 
information about the obj object. The return value points to the most derived class that 
can be made out of obj. If obj is eendy the object's most derived type, then the return 
value is obj. 


Use typeid to generate the src parameter. 


see also 
DynamicCast function, typeid, typeinfo class 


typedef void* ObjectPtr; 
ObjectPtr is a void* that points to a C++ object. 
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OC _APPxxxx messages 


OC_APPxxxx messages ocflocapp.h 


These messages are sent from ObjectComponents to the application's main window. 
They notify the application of signals and events that come from the OLE system. The 
actual message sent is WM_OCEVENT. The constants in the table below are carried in 
the message's wParam and identify particular events. To find out what each message 
carries in its /Param, look up the corresponding event handlers (such as 
EvOcAppBorderSpaceSet and EvOcAppMenus.) 


Applications that use the ObjectWindows Library can set up event handlers in their 
response tables using the EV_OC_xxxx macros defined in ocfevent.h. For more 
information about the data each message carries, see the descriptions of the 
corresponding event handlers. 


The constants beginning OC_APP indicate events typically handled in the main frame 
window. Another set of constants beginning OC_VIEW indicate events typically 
handled in the view object. 


OC_APPDIALOGHELP > The user pressed the Help button in one of the standard OLE dialog 
boxes. 

OC_APPBORDERSPACEREQ _ Asks the container whether it can give the server border space in its 
frame window. 

OC_APPBORDERSPACESET __ Asks the container to give the server border space in its frame window. 

OC_APPFRAMERECT Requests coordinates for the inner rectangle of the container's main 
window. 

OC_APPINSMENUS Asks the container to merge its menu into the shared menu bar. 

OC_APPMENUS Asks the container to install the merged menu bar. 

OC_APPPROCESSMSG Asks the container to process accelerators and other messages from the 
server's message queue. 

OC_APPRESTOREUI Tells the container to restore its normal menu and borders because in- 
place editing has ended. 

OC_APPSHUTDOWN Tells the server when its last linked or embedded object closes down. If 
the user did not launch the server directly, the server can terminate. 

OC_APPSTATUSTEXT Passes text for the status bar from the server to the container during in- 
place editing. 


See also 
OC_VIEWxxxx messages, WM_OCEVENT message 


OC _VIEWxxxx messages ocflocview.h 


These messages are sent from ObjectComponents to the application's window 
procedure. They notify the application of signals and events that come from the OLE 
system. The actual message sent is WM_OCEVENT. The constants in the table below 
are carried in the message's wParam and identify particular events. To find out what 
each message carries in its /Param, look up the corresponding event handlers (such as 
EvOcViewBorderSpaceSet and EvOcViewDrag.) 
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Ocrxxxx aspect constants 


Applications that use the ObjectWindows Library can set up event handlers in their 
response tables using the EV_OC_xxxx macros defined in ocfevent.h. For more 
information about the data each message carries, see the descriptions of the 
corresponding event handlers. 


The constants beginning OC_VIEW indicate events typically handled in the view object. 
Another set of constants beginning OC_APP indicate events that typically concern the 


application object. 


OC_VIEWBORDERSPACEREQ 
OC_VIEWBORDERSPACESET 


OC_VIEWCLIPDATA 
OC_VIEWCLOSE 
OC_VIEWDRAG 
OC_VIEWDROP 


OC_VIEWGETPALETTE — 


OC_VIEWGETSCALE 
OC_VIEWGETSITERECT 
OC_VIEWINSMENUS 
OC_VIEWLOADPART 


OC_VIEWOPENDOC 
OC_VIEWPAINT 
OC_VIEWPARTINVALID 
OC_VIEWPARTSIZE 
OC_VIEWSAVEPART 


OC_VIEWSCROLL 


OC_VIEWSETSCALE 
OC_VIEWSETSITERECT 
OC_VIEWSHOWTOOLS 


OC_VIEWTITLE 


See also 


OC_APPxxxx constants 


OCrxxxx aspect constants 


container's window. 

Requests border space for in-place editing tools in the container's view. 
Requests border space for in-place editing tools in the container's view. 
Asks the server for Clipboard data in a particular format. 

Tells server to close this remote view. 

Requests visual feedback during a drag operation. 

Accepts a dropped object. 

Asks the server for the palette it uses to paint its object. 

Asks the container to give scaling information. 

Asks container for the site rectangle. 

Asks the server to insert its menus in the menu bar for in-place editing. 


Asks the server to load its document. (The server's document contains 
one part.) 


Asks the server for the extents of its open document. 
Asks the server to paint a remote view of its document. 
Indicates that a part needs repainting. 

Asks the server for the extents of its object. 


Asks the server to save its document. (The server's document contains 
one part.) 


Asks the client to scroll its view because the user is trying to drag 
something off the edge. | 


Asks the server to handle scaling. 


Asks the container to set the site rectangle. 


Asks the server to display its tool bars in the container's window for in- 
place editing. 


Gets the title displayed in the view's window. 


ocf/ocreg.h 


These constants identify modes of presenting data. A server might be able to draw the 
same object several different ways, such as displaying its full content, creating a 
miniature representation of the content, or representing the type of object with an icon. 
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ocrxxxx Clipboard constants 


When a server registers a data format, it also registers the aspects it supports for each 
format. The values of these constants are flags and can be combined with the bitwise OR 
operator (1). 


ocrContent a 


Show the full content of the object at its normal size. 


‘DVASPECT_CONTENT 
ocrThumbnail DVASPECT_THUMBNAIL Show the content of the object shrunk to fit in a 
smaller space. 
ocricon DVASPECT_ICON Show an icon representing the type of object. 
ocrDocPrint DVASPECT_DOCPRINT Show the object as it would look if sent to the printer. 
see also 


ocrxxxx constants, REGFORMAT macro, TOcAspect enum 


ocrxxxx Clipboard constants ocflocreg.h 


These constants identify standard data formats for data that applications might share 
with each other. Use them in the REGFORMAT macro to describe the formats that your 
documents can import and export. 


ocrText 


Array of text characters 


CE_TEXT 

ocrBitmap CF_BITMAP Device-dependent bitmap 

ocrMetafilePict CF_METAFILEPICT A Windows metafile wrapped in a 
METAFILEPICT structure 

ocrSylk CF_SYLK Symbolic Link Format 

ocrDif CF_DIF Data Interchange Format 

ocrTiff CF_TIFF Tag Image File Format 

ocrOemText CF_OEMTEXT Text containing characters in the original 
equipment manufacturer's character set (usually 
ASCII) 

ocrDib CF_DIB Device-independent bitmap 

ocrPalette CF_PALETTE GDI palette object 

ocrPenData CF_PENDATA Data for pen extensions to the operating system 

ocrRiff CF_RIFF Resource Interchange File Format (often used for 
multimedia) 

ocrWave CF_WAVE A sound wave file (uses a subset of the RIFF 
format) 

ocrUnicodeText CF_UNICODETEXT Wide-character Unicode text (32-bit only) 

ocrEnhMetafile CF_ENHMETAFILE Enhanced metafile (32-bit only) 

ocrRichText "Rich Text Format" RTF tagged text format 

ocrEmbedSource "Embed Source" OLE object that can be embedded 

ocrEmbeddedObject "Embedded Object" OLE object that is already embedded 

ocrLinkSource "Link Source" | OLE object that can be linked 
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ocrxxxx direction constants 


IES P J oo P J 
| can be embedded 
ocrLinkSreDescriptor "Link Source Descriptor" Descriptive information about an OLE object that 
| can be linked 
see also 
ocrxxxx constants, REGFORMAT macro 
OCIXXxxx direction constants — oeffocreg.h 


These constants identify directions for passing data. For example, a server might be able 
to export and import bitmaps but only import metafiles. In that case, it uses ocrGetSet for 
the bitmap format and ocrGet for metafiles. 


When a server registers a data format, it also specifies whether it can get or set each 
format. 


ocrGet Imports data in the given format 

ocrSet Exports data in the given format 

ocrGetSet Both exports and imports data in the given format 
See also 


ocrxxxx constants, REGFORMAT macro 


OCrxxxx limit constants ocflocreg.h 


These constants set the maximum number of verbs and data formats that an application 
is allowed to register for any one document type. Currently these limits are both set to 8. 


ocrVerbLimit ~ Maximum number of verbs a server can register for a document 
ocrFormatLimit Maximum number of data formats an application can register for a document 
See also 


ocrxxxx constants 


OCrxxxx medium constants : ocflocreg.h 


These constants identify channels for passing data. A server might be able to pass a 
particular kind of object as a global memory handle, as a disk file handle, or through a 
data stream, tor example. 
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Ocrxxxx object status constants 


When a server registers a data format, it also registers the transfer channels it supports 
for each format. The values of these constants are flags and can be combined with the 


bitwise OR operator (| ). 


Constant = = _OLEequivalent = Meaning 
ocrHGlobal TYMED_HGLOBAL Handle to global memory soak 
ocrFile TYMED_ FILE Handle to disk file 
ocrIStream TYMED_ISTREAM Stream object in a compound file 
ocrIStorage TYMED_ISTORAGE Storage object in a compound file 
ocrGDI TYMED_GDI GDI object (such as a bitmap) 
ocrMfPict TYMED_MFPICT METAFILEPICT structure 
See also 


Oocrxxxx constants, REGFORMAT macro 


OCIXxxx Object status constants ocflocreg.h 


These constants describe how an object behaves when presented in particular aspects. 
Register these options for documents using the REGSTATUS macro. 


The values of these constants are flags and can be combined with the bitwise OR 


operator (1). 


Constan: C : oe 
career 
ocrCanLinkByOle1 
ocrCantLinkInside 
ocrInsertNotReplace 
ocrInsideOut 
ocrIsLinkObject 


ocrNoSpecialRendering 
ocrOnlyIconic 


ocrRecomposeOnkResize 


ocrRenderingIsDeviceIndependent 


ocrStatic 


“ Meaning — 


Applies only if ocrInsideOut i is set. Indicates that the abet saree to | 
be active whenever it is visible. The container is not obliged to 
comply. 

Used only in OBJECTDESCRIPTOR. Indicates that an OLE 1 
container can link to the object. 


| This object, when embedded, should not be made the source of a 


This object, when placed in a document, should not replace the 
current selection but be inserted next to it. 


The object can be activated and edited without having to install 
menus or toolbars. Objects of this type can be active concurrently. 


Set by an OLE 2 link for OLE 1 compatibility. The system sets this 
bit automatically. 


Same as ocrRenderingIsDeviceIndependent. 


The only useful way the server can draw this object is as an icon. 
The content view looks like the icon. 


When container site changes size, the server would like to redraw 
its object. (Presumably the server wants to do something other than 
scale.) 


The object makes no presentation decisions based on the target 
device. Its presentation data is always the same. 


The object is an OLE static object and cannot be edited. 
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ocrxxxx usage constants 


See also 
ocrxxxx constants, REGSTATUS macro 


ocnoxx usage constants eo octlocreg.h 


These constants tell how a server supports concurrent clients. Use them to register the 
usage key for a server. 


ocrSingleUse One client per application instance 


ocrMultipleUse Multiple clients per application instance — 
ocrMultipleLocal § Multiple clients supported by separate in-proc server 


See also 
Ocrxxxx constants, usage registration key 


OCIXxxx verb attributes constants _ ocflocreg.h 


enum ocrVerbAttributes 
These constants give the container hints about how a verb is used. Register these options 
for documents using the REGVERBOPT macro. . 


The values of these constants are flags and can be combined with the bitwise OR 
operator (| a 


s the object i in sucha | way that it needs t 


The verb ne 


ocrNeverDirties. 9g 


ocrOnContainerMenu ‘The verb should be displayed on the container's menu of object verbs when the 
object is active. The standard verbs Hide, Show, and Open should not have this — 
flag set. | 


See also 
ocrxxxx constants, REGVERBOPT macro 


OCrxxxx verb menu flags | ocfiocreg.h 


These constants describe how a server's verbs should appear on the container's menu. 
Register these options for documents using the REGVERBOPT macro. 
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OPTIONAL_ARG macro 


The values of these constants are flags and can be combined with the bitwise OR 
operator (1). 


| Constant 2 ‘Windows equivalent 2 : Meaning oo eee 
ocrGrayed _ MF_GRAYED Make the verb appear gray on the menu. This also _ 
disables the verb. 
ocrDisabled MF_DISABLED Disable the verb so the user cannot choose it. 
ocrChecked MF_CHECKED Place a check by the verb. 


ocrMenuBarBreak MF MENUBARBREAK Places the verb in anew column and adds a vertical line 
to separate the columns. 


ocrMenuBreak MF_MENUBREAK Places the verb in a new column without separating the 
columns. 


See also | 
ocrxxxx constants, REGVERBOPT macro 


OPTIONAL_ARG macro automa. 


OPTIONAL _ARG(cls, extName, default) 
An automation server uses this macro in its automation definition (after 
DEFINE_AUTOCLASS) in order to describe one argument in an exposed method. 


After an EXPOSE_METHOD or EXPOSE_METHOD_ID macro, you need to add a list of 
argument macros, one for each parameter in the method. If the argument has a default 
value, then use the OPTIONAL ARG macro. 


type is an automation class that describes the argument's data type. For example, if the 
argument is Boolean value, then type should be TAutoBool. For more information, see 
Automation Data Types. 


extName is the public name that a controller uses to refer to this argument. The string can 
be localized. 


default is the default value assigned if the caller chooses to omit the argument. 


path registration key 


The path where OLE looks to find and load the server. 


The path is optional for any server's application registration table. Usually you can omit 
the path because by default ObjectComponents records the actual path and file name of 
the server when it registers itself. 


To register a path, use the REGDATA macro, passing path as the first parameter and the 
full path string, including .EXE name, as the second parameter. 


See also 
REGDATA macro 
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permid registration key 


permid registration key 


A string that names the application without indicating any version. The permid is just 
like the progid but without a version number. It always represents the latest installed 
version of a class. 


The permid key is valid in any registration table. It is always optional. If you register 
permid, you should also register permname. Like the progid, the permid cannot be 
localized. 


To register permid, use the REGDATA macro, passing permid as the first parameter and 
the ID string as the second parameter. 


See also 
permname registration key, progid eres key, REGDATA macro, version 
registration key 


permname registration key 


A string that describes the application without indicating any version. The permname is 
just like the description but without a version number. It always represents the latest 
installed version of a class. A permname value can contain up to 40 characters. 


The permname key is valid in any registration table. It is always optional. If you register 
permname, you should also register permid. The permname string should be localized. 


To register permname, use the REGDATA macro, passing permname as the first 
parameter and the descriptive string as the second parameter. 


See also 
description registration key, permid registration key, REGDATA macro, version 
registration key 


progid registration key 


Registers a string which uniquely identifies the class. 


The string can contain up to 39 characters. The first character must be a letter. 
Subsequent characters can be letters, digits, or periods (no spaces or other delimiters). 
Conventionally, the progid value has three parts separated by periods. They are the 
program name, an object name, and a version number. The value of the progid cannot be 
localized. 


A progid string is required in every application registration table. To register a progid, use 
the REGDATA macro, passing progid as the first parameter and the identifier string as 
the second parameter. 


REGDATA(progid, "DrawingPad.Application.2") — 
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REQUIRED_ARG macro 


See also 
REGDATA macro 


REQUIRED ARG(type, extName); 
An automation server uses this macro in its automation definition (after 
DEFINE_AUTOCLASS) in order to describe one argument in an exposed method. 


After an EXPOSE_METHOD or EXPOSE_METHOD_ID macro, you need to add a list of 
argument macros, one for each parameter in the method. If the argument does not have 
a default value and is not an object, then use the REQUIRED_ARG macro. 


type is an automation class that describes the argument's data type. For example, if the 
argument is Boolean value, then type should be TAutoBool. For more information, see 
Automation Data Types. 


extName is the external, public name that a controller uses to refer to this argument. The 
string can be localized. 


TAutoBase class ocf/autodefs.h 


TAutoBase is a base class for deriving automatable objects. The class does only one thing: 
whenever an object of TAutoBase is destroyed, the destructor notifies OLE that the object 
is no longer available. 


Automated objects are not required to derive from TAutoBase. Doing so is simply a 
safeguard and matters only if the logic of the program makes it possible for the 
automated object to be destroyed by non-automated means while still connected to an 
OLE controller. ! 


If you are using TAutoBase to derive classes with explicit class specifiers that do not 
match the default specifiers for the application's model, then be sure to define the 
_AUTOCLASS macro. 


See also 
_AUTOCLASS macro 


Public destructor 


Destructor 

virtual ~TAutoBase(); | 

The virtual destructor—the only member of class TAutoBase—sends OLE an ontuary 
when the object is destroyed. The notification matters in cases where the object might be 
destroyed by non-automated means, without the knowledge of OLE, while still 
connected to an automation controller. Sending the obituary prevents a crash if OLE 
subsequently sends a command to the nonexistent object. | 
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TAutoBool struct 


TAuto Bool struct et ocf/autodefs.h 
Use TAutoBool i in an automation definition to describe the parameters and return values 
of automated methods. 

Public data member 
Classinfo 


static TAutoType ClassInfo; 
The ClassInfo member of TAutoBool holds information that identifies the Béclean data 


type. 


TAutoCommand class a ocf/autodefs.h 


TAutoCommand is an abstract base class for automation command objects. An 
automation server constructs a command object whenever it receives a command from 
an automation controller. The command object receives all parameters as VARIANT 
unions from OLE. The compiler generates calls to command object conversion functions 
‘in order to extract the proper C++ data type from the union. 


All this happens internally. Normally you should not have to construct or manipulate 
_ TAutoCommand objects directly. 


Public constructor and destructor 


Constructor 

TAutoCommand(int attr); 

Creates a command having the attributes set in the attr flag mask. The flags are defined 
in the AutoSymFlag enum. 


Destructor 
virtual ~TAutoCommand(); 
Destroys the TAutoCommand abieet. 


See also AutoSymFlag enum 


Type definitions 


TCommandHook 

typedef bool (*TCommandHook) (TAutoCommand& cmdOb)); 

Describes the prototype for a user-defined callback function called during Invoke, before 
executing the automation command object. cmdObj is the object about to be executed. If 
the callback returns false, Invoke does not execute the command. 


Seealso TAutoCommand::Invoke, TAutoCommand::SetCommandHook 
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TAutoCommand class 


TErrorMsgHook 

typedef const char* (*TErrorMsgHook)(long errCode); 

Describes the prototype for a user-defined callback function called after Invoke to 
process any error code the command might return. errCode is the status result. The 
callback is expected to return a string describing the error for the user. 


See also TAutoCommand::LookupError, TAutoCommand::SetErrorMsgHook 


Public member functions 


ClearFlag 
void ClearFlag(int mask); 
Clears all the flags in mask. The flags are defined in the AutoSymFlag enum. 


See also AutoSymFlag enum 


Execute 

virtual void Execute(); 
Executes the automation command by invoking the internal C++ member of the 
automated class to which the command belongs. 


Fail 
void Fail(TXAuto::TError); 
Throws whatever exception is indicated by the parameter. 


Seealso TXAuto::TError enum 


GetSymbol 
TAutoSymbol* GetSymbol(); 
Retrieves the symbol that generates this command. 


Invoke 
virtual TAutoCommand& Invoke(); 


Initiates the process of executing a command. The user can override the usual process 
by supplying a hook with the AUTOINVOKE macro. 


Seealso AUTOINVOKE macro, TAutoCommand::SetCommandHook 


IsPropSet 

bool IsPropSet(); 

Returns true if the asSet property flag is set. This flag indicates that the command 
assigns a value to some property of the automated class and does not return a value. 


LookupError 

static const char* LookupError(long errCode); 

Translates an error code from a function into a message string for the user. errCode is a 
function status value sent by Report. LookupError works by calling a function you have 
installed with SetErrorMsgHook. You do not have to call LookupError directly. If you have 
installed an error message hook, LookupError is called for you at the right time. 


See also TAutoCommand::Report 
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TAutoCommand class — 


Record 

virtual int Record(TAutoStack& q); | 

Records the command and its arguments by calling any hook the programmer might 
have supplied in the automation declaration with the AUTORECORD macro. 


Recording is not supported in the current version of ObjectComponents. 
See also AUTORECORD macro 


Report 

virtual long Report(); 

The AUTOREPORT macro invokes this faction to translate the status code a command 
returns into an error code. 


See also AUTOREPORT Macro 
TAutoCommand::SetErrorMsg Hook 


Return 

virtual void Return(TAutoVal& v); 

Converts whatever value the internal C++ smmand returned into a VARIANT union. 
The converted value is passed to OLE. This is what the automation controller receives as 
its return value. 


SetCommandHook 

static TCommandHook SetCommandHook(TCommandHook callback); 

Installs a user-defined callback function of type TCommandHook to be called whenever 
the command is executed. The command hook is useful for monitoring automation 
calls. 


See also TAutoCommand::Invoke, TAutoCommand::SetErrorMsgHook, 
TAutoCommand::TCommandHook typedef 


SetErrorMsgHook 

static TErrorMsgHook SetErrorMsgHook(TErrorMsgHook callback): 

Installs a user-defined callback function of type TErrorMsgHook to be called if the 
command returns an error code. 


See also TAutoCommand::LookupError, TAutoCommand::Report, 
TAutoCommand::SetCommandHook, TAutoCommand::TErrorMsgHook typedef 


SetFlag 
void SetFlag(int mask); 
Sets all the flags in mask. The flags are defined in the TAutoSymFlag enum. 


Seealso AutoSymFlag enum 
SetSymbol 
void SetSymbol(TAutoSymbol* sym); 


Assigns a symbol to the command object. The symbol is set internally. It is taken from 
the tables built by the automation definition and declaration of the automated class. 


TestFlag 
bool TestFlag(int mask); 
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TAutoCurrency struct 


Returns true if any of the flags in mask are set for this command. The flags are defined in 
the AutoSymFlag enum. 


Seealso AutoSymFlag enum 


Undo 

virtual TAutoCommand* Undo(); 

Generates a command for the undo stack by calling any hook the programmer might 
have supplied in the automation declaration with the AUTOUNDO macro. 

Undoing commands is not supported in the current version of ObjectComponents. 


See also AUTOUNDO macro 


Validate 
virtual bool Validate(); | 
Tests the validity of the command's parameters by executing whatever validation 


function or expression the programmer supplied in the automation declaration with the 
AUTOVALIDATE macro. 


Seealso AUTOVALIDATE macro 


Protected data members 


Attr 
int Attr; 
Attribute and state flags. The flags are defined in the AutoSymFlag enum. 


Seealso AutoSymFlag enum 
Symbol 
TAutoSymbol* Symbol; 


The symbol entry that generates this command. OLE passes this symbol to make this 
command execute. 


TAutoCurrency is an automation data type that helps ObjectComponents provide type 
checking for members of an automated class exposed to OLE. Use TAutoCurrency in an 
automation definition to identify currency values. 


Public data member 


Classinfo 

static TAutoType ClassInfo; 

The ClassInfo member of TAutoCurrency holds information that identifies data as a 
currency value. 
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TAutoDate struct 


Form 1 


Form 2 


TAutoDate is an automation data type that helps ObjectComponents provide type 
checking for members of an automated class exposed to OLE. Use TAutoDate in an 
autemiation definition to identify date values stored as type double. 


Public data members 


Classinfo 
static TAutoType Classinto: 
The ClassInfo member of TAutoDate holds information that identifies the date data type. 


Date 
double Date; | 
Stores a date as a 32-bit value. 


Public constructors 


Constructors 
TAutoDate(); 
Creates an empty TAutoDate. 


TAutoDate(double d); 
Creates a TAutoDate that initially holds the value in d, assumed to be a date. 


Public member function 


operator double 
operator double(); 
Returns the value stored in the Date field of TAutoDate. 


TAutoDouble is an automation data type that helps ObjectComponents provide type 
checking for members of an automated class exposed to OLE. Use TAutoDouble in an 
automation definition to identify double values. 


Public data member 


Classinfo 
static TAutoType ClassInfo; 
The ClassInfo member of TAutoDouble holds information that identifies the double data 


type. 
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TAutoEnumerator<> class 


TAutoEnumerator<> class ocf/autodefs.h 


Form 1 


Form 2 


An automation controller creates a TAutoEnumerator object to enumerate items in a 
collection held by an automation server. A collection can contain any set of similar 
values or objects that the server chooses to expose as a group. The items in the collection 
might be numbers in an array, for example, or each one might be an automated object. 


The type you pass to the template is the type of value the collection holds. If the 
collection is a set of integer values, pass int. If the collection holds automated objects, 
pass the controller's proxy class (derived from TAutoProxy). 


At first, a newly created enumerator is empty. After you call Step, the enumerator holds 
the first value in the collection. To see the value, call Value if the collection contains 
values of intrinsic data types, such as int or float, or call Object if the collection contains 
automated objects. Step, Value, and Object are the most important methods of 
TAutoEnumerator. The others are generally called for you at the right time. 


Public constructors and destructor 


Constructors 
TAutoEnumerator(); 
Constructs an enumerator object but does not attach it to any automated collection. 


TAutoEnumerator(const TAutoEnumerator& copy); 

Constructs a new enumerator object by copying an existing one. Both enumerators are 
attached to the same collection of objects. 

However it is constructed, a newly created TAutoEnumerator object does not yet hold 
any value. Always call Step to get the first item before calling Value or Object to see the 
item. 


Destructor 

~TAutoEnumerator(); 

Detaches the enumerator from its collection before allowing the enumerator to be 
destroyed. 


See also TAutoEnumerator::StepTAutoEnumerator_Step 


Public member functions 


Bind 

void Bind(TAutoVal& val); 

Connects the enumerator to the collection object, val. Bind is called internally when the 
controller passes the enumerator object to a method that returns a collection. 


Seealso ~TAutoEnumerator::Unbind 


Clear 

void Clear(); | 

Empties the enumerator so that it no longer points to any item in the collection. This 
method is called internally during Step. 
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TAutoFloat struct 


See also TAutoEnumerator::Step : 


Object 

void Object(TAutoProxy& prx); 

Returns in prx the current object from the collection. Use Object if the items in the 
collection are automated objects. If the collection contains data values, then call Value 
instead. 


To advance the enumerator so that Object returns the next object, call Step. 


Seealso TAutoEnumerator::Step, TAutoEnumerator::Value 


Step 

bool Step(); 

Advances the enumerator object one step so that Value returns the next item in the 
collection. Step returns false when called after the enumerator has reached the last item 
in the collection. 


See also TAutoEnumerator::Object, TAutoEnumerator::Value 


Unbind 
void Unbind(); 
Disconnects the enumerator object from the collection it currently enumerates. 


Seealso TAutoEnumerator::Bind 


Value 

void Value(T& v); 

Returns in v the current item from the collection. Use Value if the items in the collection 
are data values. If the collection contains objects, then call Object instead. 


To advance the enumerator so that Value returns the next item, call Step. 


Seealso J’AutoEnumerator::Object, TAutoEnumerator::Step 


TAutoFloat is an automation data type that helps ObjectComponents provide type 
checking for members of an automated class exposed to OLE. Use TAutoFloat in an 
automation definition to identify float values. 


Public data member 
Classinfo 


static TAutoType ClassInfo; 
The ClassInfo member of TAutoFloat holds information that identifies the float data type. 
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TAutolterator class 


TAutolterator class ocflautodefs.h 


TAutolterator is a pure virtual base class for iterator objects. An iterator is used to 
enumerate a collection of other objects. The iterator's methods let the caller step through 
a list of objects and examine each one in turn. 


An automation server needs to create an iterator in any automated object that represents 
a collection of other objects. To create an iterator, the server usually inserts an 
AUTOITERATOR macro in the automation definition of the collection class (after 
DEFINE_AUTOCLASS). 


In most cases, you do not need to work with the iterator class directly because the 
AUTOITERATOR macro implements the object for you. In cases where the iterator 
requires a more complex implementation, however, you might need to define the class 
directly yourself. 


You can still declare the class using AUTOITERATOR_DECLARE instead of 
AUTOITERATOR. This is just a shortcut for writing out all the standard members of an 
iterator object by hand. 


TAutolterator has five pure virtual members that any derived class must implement. 
These five functions compose a standard interface for iterators in automated collection 
objects. They are Init, Test, Step, Return, and Copy. The first four correspond to steps ina 
for loop that steps through the collection. (See AUTOITERATOR for a description of the 
correspondence.) Copy creates a duplicate iterator. 


The constructors are protected because TAutolterator should be constructed only by a 
derived class. 


Besides implementing the inherited virtual functions, a class derived from TAutolterator 
also typically declares one or more data members that record the iterator's current state. 
Usually the state variable remembers a position in the sequence of enumerated objects. 


TAutolterator is a COM object and implements the [Unknown interface. 


Public member functions 


Copy 

virtual TAutolterator* Copy()=0; 

Returns a copy of the iterator object. Your implementation should copy the iterator's 
state variables. 


Seealso T'Autolterator::Init, TAutolterator::Return, TAutolterator::Step, 
TAutolterator::Test 


GetSymbol 

TAutoSymbol* GetSymbol(): 

Retrieves the automation symbol associated with the iterator. Usually you do not need 
to call this function. 


Seealso TAutolterator::SetSymbol 
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TAutolterator class 


Init 
virtual void Init()=0; 
Initializes any state variables in the iterator. The primary task of an iterator is to loop 
through a list of objects enumerating them one by one. Init tells the iterator to prepare 
for beginning a new pass through the loop. For example, if the iterator's S state variable is 
called index, Init might say 


index = abe 


See also TAutolterator: ‘Copy, Pesto teraor: ‘Return, TAutolterator: ‘Step, 
TAutolterator::Test 


lUnknown(). 

operator IUnknown*(); 

Returns a pointer to the iterator's [Unknown OLE interface and calls AddRef on the 
interface pointer. This operator is called internally to return the iterator to OLE. Usually 
you do not need to call it directly yourself. 


Return | 

virtual void Return(TAutoVal& value)=0; 

Extracts one item from a collection and returns a reference to it in the value parameter. 
The primary task of an iterator is to loop through a list of objects enumerating them one 
by one. Return is the command that retrieves a different item from the collection on each 
pass through the loop. For example, Return might look like this: 


value = (Collection->Array) [Index] 


where value is the function's parameter, Collection points to the enclosing collection 
object, Array is a member of Collection, and Index is the iterator's state variable. 


value is type TAutoVal and represents a VARIANT union, which is the format in which 
OLE passes values. TAutoVal defines conversion operators to handle standard C++ data 
types as well as C++ strings, TAutoCurrency, TAutoData, and automated C++ objects. 
The items in a collection can be any of these types. 


Seealso J Autolterator::Copy, TAutolterator::Init, ieee ‘Step, 
TAutolterator: ‘Test 


SetSymbol 

void SetSymbol(TAutoSymbol* sym); 
Associates an automation symbol with the iterator. SetSymbol is called internally during © 
the construction of the iterator. Usually you do not need to call it directly yourself. 


Seealso T'Autolterator::GetSymbol 


Step 

virtual void Step()=0; 

Advances the iterator to point to the next item in a collection. The primary task of an 
iterator is to loop through a list of objects enumerating them one by one. Step is like the 
i++ statement in a for loop. It changes the state of the iterator to focus on the next item. 
For example, if the iterator's state variable is called index, Step might simply say 


index++; 
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TAutoLong struct 


See also 
TAutolterator::Copy, TAutolterator::Init, TAutolterator::Return, TAutolterator::Test 


Test 

virtual bool Test()=0; | 

Tests whether all items have been enumerated. The primary task of an iterator is to loop 
through a list of objects, enumerating them one by one. Test returns true if more objects 
remain to be enumerated and false when it reaches the end of the list. For example, if 
the iterator's state variable is called index, Test might say 


return (index >= NUM_ITEMS): 


Seealso J’Autolterator::Copy, TAutolterator::Init, TAutolterator::Return, 
TAutolterator::Step 


Protected constructors 


Constructors 

Form 1  TAutolterator (TServedObject& owner); 
Constructs an iterator to enumerate items held in the owner class. owner can be any 
automated class. 


Form2 _TAutolterator (TAutolterator& copy); 
Constructs an iterator by creating a copy of another iterator. Both iterators enumerate 
the same collection of objects. 


The constructors are protected because only a derived class should construct a 
TAutolterator. 


Protected data member 


Owner 

TServedObject& Owner; 

Holds a reference to the collection object that encloses the iterator. Owner is initialized 
by the constructor. The undocumented TServedObject class implements the interfaces 
that a client expects to find on an OLE object. ObjectComponents uses this class 
internally. Owner can be any automated object. 


TAutoLong is an automation data type that helps ObjectComponents provide type 
information for members of an automated class exposed to OLE. Use TAutoLong in an 
automation definition to identify long values. 


Public data member 


Classinfo 
static TAutoType ClassInfo; 
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TAutoObject <> class 


The ClassInfo member of TAutoLong holds information that identifies the long data type. 


Form 1 
Form 2 
Form 3 


Form 4 


Form 1 
~ Form2 


Form 3 


TAutoObject holds a pointer to a C++ object. TAutoObject casts the pointer to different 
data types appropriately when an automation operation requires conversion. It also 
retrieves type information about the object when needed during automation. Think of 
TAutoObject as a smart pointer. 


ObjectComponents often creates smart pointers for you. Usually you do not need to 
manipulate TAutoObject objects directly. 


Public constructors 


Constructors 
TAutoObject(); 
Constructs an empty TAutoObject that contains no pointer. - 


TAutoObject(T* point); 
Constructs a TAutoObject that holds the pointer point. 


TAutoObject(T& ref); 
Constructs a TAutoObject that holds a pointer to the object ref. 


TAutoObject(IDispatch* dispatch); 

Attempts to read type information from the object that owns the [Dispatch interface. If it 
succeeds, the constructor builds a TAutoObject around a pointer to the C++ object. If it 
fails, the constructor throws a TXAuto::xTypeMismatch exception. 


Public member functions 


operator *() 
T& operator *(); 


The dereference operator returns a reference to the object whose pointer TAutoObject 
holds. 


operator = 
void operator =(T* point); 
Places the point pointer in the TAutoObject. 


void operator =(T& ref); 
Places a pointer to the object ref in the prea 


void operator =(IDispatch* dispatch); 


_ Attempts to read type information from the object that owns the [Dispatch interface. If it 


succeeds, the operator places in the TAutoObject a pointer to the C++ object. If it fails, the 
constructor throws a TXAuto::xTypeMismatch exception. 


The assignment operators place a pointer to a C++ object in the TAutoObject. They are 
usually used to initialize the TAutoObject after creating it with the default constructor. 
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TAutoObjectByVal<> class 


operator T& () 

T& operator*(); 

The dereference operator returns a reference to the object whose pointer TAutoObject 
holds. 


operator T* () 
operator T*(); 
Returns a pointer to the object TAutoObject holds. 


TObjectDescriptor() 

operator TObjectDescriptor(); 

Constructs and returns a new object descriptor object based on the pointer that 
TAutoObject holds. This operator is called internally to obtain type information for 
constructing an automation object. 


Protected data member 


operator P 
T* P: 
Returns the pointer that TAutoObject holds. 


Base class 

TAutoObjectDelete 

An automation server uses this class when an automated method needs to return a copy 
of an object. Usually you do not have use the class directly because the automation 
macros make the proper declarations for you. 


To return an object, TAutoObjectByVal clones the object by calling its copy constructor. 
The clone is passed to the automation controller as the return value from some 
automation command. TAutoObjectByVal holds on to the cloned object until the 
controller releases it. Then it destroys the object by calling its destructor. 


In other respects, TAutoObjectByVal closely resembles its parent class, TAutoObjectDelete. 


See also 
TAutoObjectDelete 


Public data member — 


operator = 

void operator =(T obj); 

This operator creates a new object of type T by copying the original object, obj. The copy 
is passed to an automation controller as the return value from an automated method. T 
is the data type passed into the template. 
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TAutoObjectDelete <> class 


Form 1 


Form 2 


- Public constructors 


Constructors 


‘TAutoObjectByVal(); 


Creates an empty TAutoObjectByVal. 


TAutoObjectByVal(T obj); 


Creates a TAutoObjectByVal that holds a copy of the object obj.” T is the data type passed 
into the template. | 


Form 1 
Form 2 


Form 3 


Form 1 


Base class 


TAutoObject 

An automation server uses this class when an automated method needs to return an 
object to an automation controller. Usually you do not have use the class directly 
because the automation macros make the proper declarations for you. 


Like its parent class TAutoObject, TAutoObjectDelete exists in order to hold a pointer to an 
object and convert it as necessary when the object is passed from server to client through 
automation calls. The difference between the two classes is that when the automation 
controller is through with the automated object, TAutoObjectDelete informs the 
connector object that it can let the automated C++ object call its destructor. 


See also 
TAutoObject class 


Public constructors 


Constructors 
TAutoObjectDelete(); 
Creates an empty TAutoObjectDelete object. 


TAutoObjectDelete(T* p); 
Creates a TAutoObjectDelete object from a pointer to another object. 


| TAutoObjectDelete(T& 1); 


Creates a TAutoObjectDelete object from a reference to another object. 


The TAutoObjectDelete constructors do nothing but pass their parameters back to the 
parent class, TAutoObject. 


Public member functions 


operator = 
void operator =(T& 1); 
Tells TAutoObjectDelete to hold a pointer to the object referred to by r. 
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Form 2 


TAutoProxy class 


void operator =(T* p); 
Tells TAutoObjectDelete to hold the pointer p. 


TObjectDescriptor() 
operator TObjectDescriptor(); 
Returns type information describing the object. 


Form 1 


Form 2 


An automation controller derives classes from TAutoProxy to represent automated OLE 
objects that it wants to command. To send commands to an automated object, the 
controller invokes methods on the proxy that represents the object. ObjectComponents 
connects the proxy to the original so that invoking members of the proxy also invokes 
members of the automated object. 


A proxy object must inherit from TAutoProxy. In the derived class, the controller 
declares one method for each command it wants to send. The declared methods must 
match the prototypes of the desired commands. To implement these proxy methods, the 
controller uses three macros: AUTONAMES, AUTOARGS, and AUTOCALL. The 
macros insert code that calls down to the base class. TAutoProxy passes the commands 
to OLE. 


Usually you do not have to call anything in TAutoProxy directly. All you have to do is 
derive your proxy class from TAutoProxy and implement the methods with the proxy 
macros. 


To generate proxy classes quickly and easily, use the AUTOGEN.EXE tool in the 
OCTOOLS directory. AUTOGEN reads the automation server's type library and writes 
all the necessary headers and source files for your proxy objects. 


Public destructor 


Destructor 
~TAutoProxy(); 
Destroys the TAutoProxy object. 


The constructors are protected because only derived proxy classes should call them. 


Public member functions 


Bind 

void Bind(IUnknown* obj); 

Binds the proxy object to a server identified by a pointer to its [Unknown interface. 
Throws a TXOle exception for failure. 


void Bind(IUnknown& obj); 
Binds the proxy object to a server identified by a reference to its [Unknown interface. 
Throws a TXOle exception for failure. | 
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TAutoProxy class. 


Form 3 


Form 4 
Form 5 


Form 6 


Form 7 


Form 1 
Form 2 


Form 3 


void Bind(const GUID& guid); 
Binds the proxy object to a server identified by its globally unique ID (GUID). This is the - 
clsid that the server registered for objects et the type you want to control. Throws a 
TXOle exception for failure. 


void Bind(char far* progid); 
Binds the proxy object to a server identified by its progid. (This is the GUID that the 
server registered to identify the application itself.) Throws a TXOle exception for failure. 


void Bind(TAutoVal& val): 

Attempts to intrepret the value in the TAutoVal union as a reference to an Dispatch 
object and bind to the [Dispatch directly. Throws a True exception if the ee does 
not support [Dispatch. 


void Bind(IDispatch* obj); | 
Accepts obj as the proxy object's server. 


void Bind(IDispatché& obj); 
Accepts obj as the proxy object's server. 


The Bind function attempts to open a channel of communication to the automation 
server in order to send commands. More specifically, Bind requests a pointer to the 
server's [Dispatch interface. 


Bind is called internally when the object is passed as the return object for another proxy 
method. Which form of Bind is used depends on what information available to identify 
the server. | 


See also TAutoProxy::Bind 


IDispatch&() 
operator IDispatch&(); 
Returns a reference to the [Dispatch interface of the proxy object's server. 


IDispatch*() 

operator IDispatch*(); 

Returns a pointer to the [Dispatch interface of the proxy object’ s server and calls AddRef 
on the interface pointer. 


IsBound 

bool IsBound(); 

Returns true if the server already has a pointer to the [Dispatch interface of its server and 
false if it does not. 


Lookup - 
long Lookup(char far* name); 
Calls the server to get the ID that matches the name. 


long Lookup(const long id); ~ 
Returns the value passed in as id. 


void Lookup(const char* names, long* ids, unsigned count); 
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TAutoProxy class 


Looks up a series of names and returns all their IDs at once. names and ids point to two 
parallel arrays. count gives the number of elements in both arrays. With a single call to 
OLE, Lookup fills the ids array with numbers to identify all the names. 


Given the name of a command or an argument, Lookup calls the server to ask for the 
corresponding ID values. Although commands and arguments have names for the 
convenience of programmers, OLE actually identifies them by numbers. A server must 
find out the ID number in order to execute the command. 


MustBeBound 

void MustBeBound(); 

Throws a TXAuto exception if the TAutoProxy object does not have an [Dispatch interface 
for its server. TAutoProxy calls this method internally before performing actions that 
assume the object is already bound to the server. 


SetLang 

void SetLang(TLangld lang); 

Sets the locale ID that the controller will pass to the server with each command. The 
locale ID tells the server what language the controller is using. 


See also Locale IDs, TAutoStack 


Unbind 

void Unbind(); 

Decrements the reference count of the proxy object's server and erases internal 
references to the server. 


See also: ‘TAutoProxy::Bind 


Protected constructor 


Constructor 

TAutoProxy(TLangld lang); 

Constructs a TAutoProxy object and sets the object to use the language identified by the 
lang locale ID. 


See also Locale IDs 


Protected member function 


Invoke 
TAutoVal& Invoke(int attr, TAutoProxyArgs& args, long* ids, unsigned named=0); 
Sends a command to the automation server. Invoke is called by the AUTOCALL macros. 


attr describes the type of command being issued and can be a combination of the 
AutoCallFlag enum values. 


The args object contains all the values passed as arguments to the command. 


ids points to an array of ID values identifying the command and the arguments. There 
should be one ID value for each element in the args array. 
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TAutoShort struct 


names tells how many arguments in args are identified by name. 
Seealso AutoCallFlag enum, AUTOCALL_xxxx macros 


TAutoShort is an automation data type that helps ObjectComponents provide type 
checking for members of an automated class exposed to OLE. Use TAutoShort in an 
automation definition to identify short values. 


Public data member 


Classinfo 
static TAutoType Classinfo; 
The ClassInfo member of TAutoShort holds information that identifies the short data 


type. 
TAutoStack class | ocf/autodefs.h 


TAutoStack processes the command stack that an automation controller sends to an 
automation server through OLE. The command stack contains a dispatch ID identifying 
a particular command and a set of VARIANT unions containing all the arguments 
needed to execute the command. 


ObjectComponents interprets the dispatch ID and extracts the proper C++ value from 
each union. It builds a command object (TAutoCommand) and calls the command's 
Execute method. TAutoCommand in turn invokes the methods you have exposed by 
declaring them and defining them in your automated classes. 


The stack also carries a locale ID identifying the language used in the command. 
ObjectComponents takes the locale into account when interpreting strings it extracts 
from the stack. If you have provided localization resources, then ObjectComponents 
translates to the requested language for you. 


Usually you do not have to work with TAutoStack directly. ObjectComponents 
automatically passes a stack in to the proper command object for you. The command 
objects are created by the automation declaration macros. | 


See also 
TAutoCommand class 


Public constructor and destructor 


Constructor 
TAutoStack(TServedObject& owner, VARIANT far* stack, TLocaleld locale,int argcount, int namedcount, 
long far* map); 
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TAutoStack class 


The constructor is called only internally. You should not need to construct your own 
stack. 


owner is the automated object to which the command is directed. 


stack points to a series of contiguous unions of type VARIANT. The unions contain 
values or object references passed in automation commands. 


locale is a locale ID describing the language the controller is using. 
argcount tells how many arguments follow the dispatch ID in the stack. 


namedcount tells how many of the arguments were passed with their names. A controller 
can pass arguments in any order, and even omit optional arguments, if it identifies the 
arguments it does pass explicitly by the name the server gives them. 


if namedcount is greater than zero, then map points to an array of ID values 
corresponding to the argument names passed by the constructor. 


map is a table for translating named argument IDs to argument positions. 


Destructor 
~TAutoStack(); 
Destroys the T’AutoStack object. 


Public member function 


operator [] 

TAutoVal& operator|](int index); | 

Extracts individual arguments from the command stack for use as C++ function 
arguments. index is a zero-based index into the command's argument list, which follows 
the order established in the corresponding EXPOSE macro of the automation definition. 
This operator is called by the command objects generated in the automation declaration. 


If index is out of range, the operator throws a TXAuto::xNoArgSymbol exception. 


Public data members 


ArgCount 
const int ArgCount; 
Holds the number of arguments passed on the command stack (named or unnamed). 


ArgSymbolCount 
int ArgSymbolCount; 
Holds the number of command arguments exposed to automation. 


CurrentArg 

int CurrentArg; 

As ObjectComponents processes the arguments on the stack one by one, this member 
indexes the current argument. When CurrentArg reaches ArgCount, all the arguments 
have been processed. 
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TAutoString struct 


Langld 
TLangld Langld; 
Holds a number that identifies the language the controller is using to send commands. 


Owner 
TServedObject& Owner; | 
Refers to the automated object that is processing the command on the stack. 


_ Symbol 


int ArgSymbolCount; 
Holds the number of command arguments exposed to automation. 


Constant 


SetValue 

TAutoStack::SetValue 

SetValue is a predefined standard dispatch ID. The dispatch ID is a number that 
identifies a particular command that an automated object can execute. The only two 
standard dispatch IDs used in ObjectComponents are 0 for an object's default action and 
-3 for a command that sets the value of a property. SetValue is —3. 


See also TAutoVal class, TLocaleld 


TAutoString struct atte 


Form 1» 


Form 2 


Form 3 


An automation server uses T’AutoString to describe C string types in an automation | 
definition. The member functions of the TAutoString structure facilitate copying and 
assigning string values with minimal memory reallocations when strings are passed 
back and forth between servers and controllers. 


You do not need to use TAutoString with C++ string objects. For more information, see 
Automation Data Types. 


TAutoString works best with const string values. When passed a non-constant string, 
TAutoString must make an internal copy. When the string is const, TAutoString knows 
the value will not change and can skip the copying step. The performance improvement 
is significant. 


Constructors 
TAutoString(const string& s); 
Creates a TAutoString and assigns it the string held j in a C++ string Shee 


TAutoString(const TAutoString& copy); 
Creates a new TAutoString that holds the same string value as the copy object. 


TAutoString(TAutoVal& val); 
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Form 4 


Form 5 


Form 1 


Form 2 


Form 3 


TAutoString struct 


Initializes the new object with the value in a TAutoVal union. TAutoVal represents the 
VARIANT data type OLE uses to pass values between two applications. It is a union of 
many types. This constructor extracts the value from the union as a string. 


TAutoString(const char far* str); 
Initializes the new object with the value in a const C string. 


TAutoString(BSTR s, bool loan) 
Initializes the new object with the value in a BASIC-style string, one preceded by its 
length and not terminated by null. That is the format OLE uses for passing strings. Set 


loan to true if the TAutoString object owns the BSTR and false if it only references the 
BSTR. 


Destructor 

~TAutoString(); 

TAutoString maintains a reference count on the string object it contains. The destructor 
decrements the reference count. 


Public member functions 


int() 
operator int() 
Returns the length of the string value (as strlen would calculate the length). 


operator = 
TAutoString& operator =(const char far* str); 
Accepts a C-style const string as the new value of the TAutoString. 


TAutoString& operator =(char* s); 

Accepts a C-style non-const string as the new value of TAutoString. Because the string is 
not constant, TAutoString must create a new copy of the string for itself. This makes 
Form 3 significantly slower than Form 1. Try to pass const strings where possible. 


TAutoString& operator =(const TAutoString& copy) 
Sets the value of the TAutoString object to be a string copied from another TAutoString 
object. 


char*() 

operator char*(); 

Returns the object's string value in the form of a non-const C-style string. To do this, 
TAutoString must create a new copy of the string. It is faster to assign to a const char* 
where possible. 


const char far*() 
operator const char far*(); 
Returns the object's string value in the form of a const C-style string. 


Public data member 


Classinfo 
static TAutoType Classinfo; 
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This static structure holds a number that identifies the data type as a string. All the 
automation data types hold a similar static identifier so that ObjectComponents can 
Re any of them to determine what they a are. 


EAutolypesiruct ttt. 


The TAutoType structure is a static data member of all the automation data type classes, 
such as TAutoBool and TAutoString. TAutoType makes all these data types self- _ 
describing. This is an essential quality for dealing with the VARIANT unions that OLE 
uses to pass values during automation. Because all the automation types derive from 

_ TAutoType, ObjectComponents can process values of any type with the same code. 
Because TAutoT ype is self-describing, ObjectComponents can always determine the 
actual type of any particular item. 


Usually you do not have to work with TAutoT ype directly, just with the automation 
types that derive from it. 


Public member function 


GetType 

— short GetType(); | 
Returns an integer that identifies a particular data type. The identifiers are defined in the 
AutoDataType enum. / 


Seealso AutoDataType enum 


TAutoVal class | ocf/autodefs.h 


TAutoVal duplicates the VARIANT type that OLE uses to pass values between an 
automation server and controller. It also adds access methods to retrieve the value in the 
VARIANT. A VARIANT can be cast to type TAutoVal, and TAutoVal can be cast toa 
VARIANT. 


A VARIANT is a large union with fields of many different data types. A large set of 
overloaded assignment operators allow many different kinds of values to be stored ina 
TAutoVal object. Each assignment operator also records internally a number that 
identifies the type of value just received. A similar set of conversion operators allows the 
value in the object to be cast to different types of values. Whether a particular conversion 
succeeds depends on the type of value in the object. A string cannot be cast to some 
other object, for example. If the conversion fails, TAutoVal throws an exception of type 
TXAuto::xConversionFailure. 


ObjectComponents treats the data passed between an automation server and controller 
as a stack of unions. The stack is TAutoStack, and the items on the stack are TAutoVal. 
Because the server and controller are built separately and can use different _ 
programming languages, data passed between them cannot retain an intrinsic type. 
Command identifiers and argument values are passed as VARIANTs. The recipient of a 
VARIANT value must rely on the item's context in order to determine what BIyPe the 
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value is supposed to be. For example, when it sees a dispatch ID for a command that 
expects two integer arguments, the application extracts integers from the next two 
VARIANTs. 


Public member functions 


operator = 

void operator=(int i); 

void operator=(int far* p); 

void operator=(long }); 

void operator=(long far* p); 

void operator=(unsigned long 1); 

void operator=(unsigned long far* p); 

void operator=(short 1); 

void operator=(short far* p); 

void operator=(float i); 

void operator=(float far* p); 

void operator=(double i); 

void operator=(double far* p); 

void operator=(TBool i); 

void operator=(TBool far* p); 

void operator=(const char far* s); 

void operator=(string s); 

void operator=(TAutoString s): 

void operator=(TAutoCurrency i); 

void far* operator=(TAutoCurrency far* p); 
void operator=(TAutoDate i); 

void far* operator=(TAutoDate far* i); 

void operator=(TAutoVoid); 

void operator=(IDispatch* ifc); 

void operator=(IUnknown* ifc); 

void operator=(TObjectDescriptor od); 
Assignment operators initialize TAutoVal by placing in the oprerEe both the assigned 
value and an ID to show the type of the assigned value. 


This table describes those data types that are not standard C types. 


Type S : : Description FS 2 oe 

Dispatch ~ Adiass OBIE Companion uses se anferaliy to peers the standard OLE _ | 
interface called [Dispatch, supported by automatable objects 

TUnknown A class that ObjectComponents uses internally to implement the standard 
IUnknown OLE interface, supported by all OLE objects 

string C++ string object 

TAutoCurrency An automation data type that holds a currency value 

TAutoString An automation data type that holds a C-style string value _ 

TAutoVoid An automation data type that represents a void return 

TObjectDescriptor A class that ObjectComponents uses internally to hold information about an OLE 


object 
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See also Automation data types, String class 


Clear — 

void Clear(); 

Clears the value stored in the beet ieavine it empty. This method cannot be called on 
the objects managed by TAutoStack. 


Seealso TAutoStack class 


Copy 
void Copy(const TAutoVal& copy); 


Copies the TAutoVal object into copy. Intelligently allocates space for a string, if needed, 
and calls AddRef if the value in the union is an OLE object. 


double far*() 
operator double far*(); 
Returns a pointer to a double value. 


-double() 
operator double(); 
Returns the value in the object as a double value. 


int far*() 
operator int far*(); 
Returns a pointer to an int. 


float far*() 
operator float far*(); 
Returns a pointer to a floating-point value. 


float() 
operator float(); 
Returns the value in the object as a floating-point value. 


GetDataType 
int GetDataType(); 
Returns an integer identifying the type of value that was assigned to the union. 


IDispatch&() 
operator IDispatch&(); | 
Extracts an [Dispatch interface from the value in the TAutoVal object. [Dispatch is the 


standard OLE interface supported by automatable objects. This method does not call 
AddRef on the [Dispatch interface. 


~Seealso TAutoVal::[Dispatch*() 
IDispatch*() 
operator IDispatch*(); 
Extracts an [Dispatch interface from the eae in the TAutoVal object. [Dispatch is the 


standard OLE interface supported by automatable objects. This function also calls the 
interface's AddRef method. _ 


Seealso T’AutoVal::[Dispatch&() 
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int() 
operator int(); 
Returns the value in the object as an integer. 


int far*() 
operator int far*(); 
Returns a pointer to an int. 


IsRef 
bool IsRef(); 
Returns true if the value assigned to the union is a reference to a value. 


lUnknown&() 

operator IUnknown&(); 

Extracts an [Unknown interface from the value in the TAutoVal object. [Unknown is the 
standard OLE interface supported by all objects. This method does not call AddRef on 
the [Unknown interface. 


Seealso TAutoVal::[Unknown*() 


lIUnknown*() 

operator [Unknown*(); 

Extracts an [Unknown interface from the value in the TAutoVal object. [Unknown is the — 
standard OLE interface supported by all objects. This method calls AddRef on the - 
[Unknown interface. 


Seealso TAutoVal::[Unknown&() 


long() 
operator long(); 


Returns the value in the object as a long integer. 


long far*() 
operator long far*(); 
Returns a pointer to a long integer. 


short() 
operator short(); 
Returns the value in the object as a short integer. 


short far*() 
operator short far*(); 
Returns a pointer to a short integer. 


string() 
operator string(); 
Returns the value in the object as a C++ string object. 


TAutoCurrency() 
operator TAutoCurrency(); 
Returns the value in the object as a currency value. 


Seealso TAutoCurrency class 
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TAutoCurrency far*() 
operator TAutoCurrency far*(); 
Returns a pointer to a currency value. 


Seealso T’AutoCurrency 


_ TAutoDate() 
operator TAutoDate(); 
Returns the value in the object as a date value. 


See also TAutoDate class 


TAutoDate far*() 
operator TAutoDate far*(): 
Returns a pointer to a date value. 


Seealso TAutoDate class 


TBool() 
operator TBool(); 
Returns the value in the object as a Boolean value. 


TBool far*() 
operator TBool far*(); 
Returns a pointer to a Boolean value. 


TUString*() 

operator TUString*(); 

Returns the value in the object as a TUString object. TUString is a reference-counted 
union of various string representations. It is used internally by ObjectComponents for 
implementing TAutoString. 


unsigned long() 
operator unsigned long(); 
Returns the value in the object as an unsigned long integer. 


unsigned long far*() 

operator unsigned long far*(); 
Returns a pointer to a long integer. (TAutoVal does not distinguish long from unsigned © 
long.) 


Seealso TAutoStack class 


TAutoVoid is an automation data type like TAutoShort and TAutoBool. Use it in an 
automation definition to describe functions that return no value. 7 


The purpose of the structure is to implement the assignment of void to a TAutoVal. 
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See also 
TAutoVal struct 


Public data member 


Classinfo 

static TAutoType Classinfo; 

As with any automation data type, the ClassInfo member holds a value that identifies a 
data type, in this case void. 


Seealso TAutoType struct 


typedef |Unknown* (*TComponentFactory) (IUnknown* outer, uint32 options, uint32 id = 0); 
TComponentFactory is a type definition for a callback function. 


outer points to the [Unknown interface of an external OLE object under which the 
application is asked to aggregate. If outer is 0, then either the new object is independent 
or it will become the outer object in an aggregation. 


options contains bit flags indicating the application's running state. To test the flags, use 
the TOcAppMode enum constants. 


id is anumber ObjectComponents assigns to identify a particular type of object the 
application can create. If id is 0, the application is asked to create itself. To request 
particular document types, ObjectComponents passes the document template ID. 


The return value is a pointer to the [Unknown interface of whatever object the callback 
function creates, either the application itself or one of its objects. During aggregation, the 
return value becomes the inner [Unknown pointer in some other object. (Unknown is a 
standard OLE type declared in compobj.h.) 


A callback of type TComponentFactory is passed to the constructor of an application's 
registrar object (either TOcRegistrar for a linking and embedding application or 
T Registrar for an application that supports automation only). 


See also TOcAppMode enum, TOcRegistrar class, TRegistrar class 


typedef unsigned long TLocaleld; 

A locale ID is a 32-bit value that identifies a language. The low half of the value is a 16- 
bit language ID. In the current OLE definition, the upper word is reserved, so in effect a 
locale ID is a 32-bit language ID. 


Windows uses locale IDs to set the system's default language. ObjectComponents uses 
locale IDs in automation. An automation controller passes a locale ID to the server with 
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every command. The server is expected to interpret the commands it receives as strings 
in the given language. 


There are two predefined system locale settings in the olenls.h header. 


LOCALE_SYSTEM_DEFAULT _ The default locale set for the system. 


LOCALE_USER_ DEFAULT The default locale set for a particular user (which can differ from the 
| system setting on multiuser systems). 


See also Langxxxx language ID constants, TLangld typedef 


Base class 

TUnknown 

TOcApp is an ObjectComponents connector object for a linking and eapedaing 
application. It implements the interfaces an application needs for communicating with 
OLE. Any ObjectComponents application that supports linking and embedding needs 
to have a TOcApp object. Usually it is created for you by your TOcRegistrar object. 


Applications that support automation but do not support linking and embedding do 
not need a TOcApp object. They create a TRegistrar instead of a TOcRegistrar. 


TOcApp is a COM object and implements the [Unknown interface. 


See also 
TOcModule::OnInit, TOcRegistrar class, TOleFactory<> class, TRegistrar class, 
TUnknown class 


Type definitions © 


TOcMenuEnable 

enum TOcMenuEnable | | 

These enumeration values are flags that can be combined with the bitwise OR operator 
(|). A container passes them to the EnableEditMenu function in order to determine which 
OLE commands on the Edit menu should be enabled. The answer depends on whether 
the container supports any of the data formats currently present on the Clipboard. 


EnablePaste The Paste command places an object from the Clipboard in the open 
| : document. The format of the new data object depends on what the server 
prefers and the container supports. 


EnablePasteLink The Paste Link command adds to the open document a link to the object on 
the Clipboard. 
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Constant : : Menu command enabled 


EnableBrowseClipboard The Paste Special command favokes a standard Hiloe box that slice all 
the data formats available for the object currently on the Clipboard and lets 
the user choose among them. 


EnableBrowseLinks The Links command displays a list of all the linked objects in the open 
document, allowing the user to update or delete them. 


See also REGFORMAT macro, TOcApp::EnableEditMenu 


Public member functions 


AddUserFormatName 

void AddUserFormatName(char far* name, char far* resultName, char far* id = 0); 

Call this function to associate a result name with a Clipboard format. The resultName 
parameter describes the data format to users and appears in Help text of the Paste 
Special dialog box. Use one of the other two parameters to identify the associated 
Clipboard format. This method is used only if you have a non-standard, private 
Clipboard format that you want to associate with names used in the Paste Special dialog 
box. 


A custom format must first be entered in the application's registration tables using the 
REGFORMAT macro. For example, 


REGFORMAT(0, “DrawingClip", ocrContent, ocrIStorage, ocrGet); 


"DrawingClip" becomes the ID string that Windows uses internally to identify the 
custom format. To associate more descriptive strings with the custom format, call 
AddUserFormatName: 


AddUserFormatName("DrawingPad", "a freehand drawing", "DrawingClip"); 


The name of the "DrawingClip" format is now "DrawingPad". If the user chooses Paste 
Special when data of this type is on the Clipboard, the name in the dialog box is 
"DrawingPad". It is perfectly legal for the ID and the name to be the same string. 


The result string, "a freehand drawing", typically appears in the Help text during a Paste 
Special operation. 


See also REGFORMAT macro 


Browse 

boo! Browse(T Ocinitinfo& initinfo); 

Displays the Insert Object dialog box allowing the user to choose from available servers 
to create a new object in the open document. Returns true if the user inserts an object 
and false if the user cancels. 


Create initInfo first by passing to its constructor the view object where the new object 
will be inserted. Browse fills initInfo with information about the object. Then use initInfo 
to create anew TOcPart. 


See also TOclInitInfo, TOcPart, TOcView 
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BrowseClipboard | 

bool BrowseClipboard(TOcInitInfo& initInfo); 

Displays the Paste Special dialog box showing the available formats for the data 
currently on the Clipboard, allowing the user to choose what format to paste. Returns 
true if the user pastes data and false if the user cancels. 


Create initInfo first by passing to its constructor the view object where the new object 
_ will be inserted. Browse fills initInfo with information about the object. Then use initInfo 
to create a new TOcPart. 


This function is called by TOcView::BrowseClipboard ; 
Seealso TOclInitInfo, TOcPart, TOcView 


CanClose 

bool CanClose(); 

A container calls this function to determine whether it can shut down. CanClose polls all 
the connected servers and attempts to close them. It returns true if it is safe to close the 
application. 


Clip 
bool Clip(IBPart far* part, bool link, bool embed, bool delay = false); 


Copies the currently selected object to the Clipboard. Usually you do not have to call 
Clip directly because TOcView::Copy does it for you. 


part points to the linked or embedded object. You can pass an object of type TOcPart for 
this parameter. (TOcPart supports the [BPart interface, which is defined in the BOCOLE 
library.) If link and embed are both true, then other applications can either link or embed 
the object when they paste it from the Clipboard. Make delay true to have 
ObjectComponents provide delayed rendering of alternate data formats. (Delayed 
rendering saves memory. For more information, refer to the Clipboard Overview in the 
API Help file. Look for the topic "Clipboard Operations.) 


Seealso TOcPart, TOcView::Copy 


Convert 

bool Convert(TOcPart* ocPart, bool activate); | 

Displays the Convert dialog box where the user can alter the aspect or format of a linked 
or embedded object. ocPart points to the object the user wants to modify. 


Make activate true if you want ObjectComponents to activate the object after converting 
it. Generally activate should be false if the user has chosen Links from the Edit menu. If 
the user tries to activate an object whose server is not present, you can offer the option of 
converting the object to another server, and in that case activate should be true. 


Seealso TOcPart 


Drag 
bool Drag(IBPart far* part, TOcDropAction inAction, TOcDropAction& outAction); 

_ Acontainer calls this function when the user wants to drag one of the container's objects. 
The first parameter, part, is the object the user is trying to drag. Usually this is an object 
of type TOcPart. (TOcPart suppers the [BPart interface, which is defined in the © 
BOCOLE library.) | | 
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inAction combines bit flags indicating possible drag actions the application supports. 
The flags indicate whether the user can move, copy, or link the object. The value 
returned in outAction contains just one of the action flags indicating what actually did 
happen. 


Seealso TOcDropAction enum, TOcPart 


EnableEditMenu 

uint EnableEditMenu(TOcMenuEnable enable, IBDataConsumer far* ocview); 

An application calls EnableEditMenu to find out which of the OLE-related commands on 
its Edit menu should currently be enabled. The flags combined in enable indicate the 
commands to be tested, and the return value uses the same bit flags to indicate which 
commands to enable. ocview is usually an object of type TOcView. (TOcView supports the 
IBDataConsumer interface, which is defined in the BOCOLE library.) 


TOleContainer and TOleView call TOcApp::EnableEditMenu in the command enabler 
functions for the Edit menu. 


See also TOcApp::TOcMenuEnable enum, TOcView 


EvActivate 

void EvActivate(bool active); 

A container calls this function to tell OLE when its frame window becomes active or 
inactive. Make active true if the window was activated or false if it was deactivated. 


Seealso TOcApp::EvResize, TOcApp::EvSetFocus 


EvResize 

void EvResize(); 

A container calls this function to tell OLE when the size of its frame window (the main 
window) has changed. OLE might need this information to let a server modify its tool 
bar during in-place editing. 


See also TOcApp::EvActivate, TOcApp::EvSetFocus 


EvSetFocus 

bool EvSetFocus(bool set); 

A container calls this function to tell OLE that its frame window has either received or 
yielded the input focus. Make set true if the window gained the focus or false if it lost 
the focus. 


See also TOcApp::EvActivate, TOcApp::EvResize 


GetName 
string GetName() const; 
Returns a string object containing the application's name. 


GetNameList 

TOcNameList& GetNameList(); | 
Returns an array of TOcNameList objects containing the names of all the Clipboard 
formats the application supports. The TOcView class uses this list when executing the 
Paste Special command. The list provides the names and Help strings associated with 
the formats. 
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See also TOcN ameList | 


GetRegistrar() 

TOcRegistrar& GetRegistrar(); 
Returns the application's registrar object. oo is the same object passed into the TOcApp | 
constructor. 


Seealso TOcApp public constructor and destructor, TOcRegistrar class 


IsOptionSet 

bool IsOptionSet(uint32 option) const; 

Tests the application mode flags and returns true if those set in option are set for the 
application. The application mode flags are defined in the TOcAppMode enum. 


See also ia ae TOcAppMode enum 


Paste 

bool Paste(TOcInitInfo& initinfo); 

Fills initInfo with information about the object on the Clipboard. Returns true if it 
succeeds in gathering information and false if it fails. 


Create initInfo first. The TOcInitInfo constructor receives the view object where the new 
part will be inserted. Then call Paste to put information in initInfo. Finally, call 
TOcView::Drop to put the object in the view. 


This function is called by TOcView::Paste. 
Seealso TOcInitInfo, TOcView, TOcView::Drop, TOcView::Paste 


RegisterClass 

bool RegisterClass(const string& ase BCID classld, bool multiUse); 

Tells OLE that the application is capable of producing objects of a certain type. What 
objects a server can produce depend on the types of documents it registers. 


progid is the registered string that identifies a type of object. 


RegisterClasses loops through the application's document templates and calls 
RegisterClass once for each type. The call is made internally and usually you do not need 
to invoke either function directly. 


Seealso TOcApp::RegisterClasses, TOcApp::UnregisterClass, 
TOcApp::UnregisterClasses 


RegisterClasses 

void RegisterClasses(const TDocTemplate* tplHead = ::DocTemplateStaticHead); 

Announces to OLE that the application is running and tells OLE about each type of 
document the application has registered. The document types are exposed to OLE as 
kinds of objects the application can produce. RegisterClasses tells OLE who you are and 
what you can make. 


tplHead points to the beginning of the application's list of document templates. 
ObjectWindows stores this list in the global variable DocTemplateStaticHead. | 
UnregisterClasses loops through the list of document types and calls UnregisterClass for 
each one that has a registered progid. 
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RegisterClasses loops through the document structures in tplHead and calls RegisterClass 
once for each type that has a progid. The call is made internally, and usually you do not 
need to invoke either function directly. 


Seealso progid registration key, TOcApp::RegisterClass, TOcApp::UnregisterClass, 
TOcApp::UnregisterClasses 


ReleaseQObject 

virtual void ReleaseObject(); 

ReleaseObject notifies the object that the application's main window is gone. If the 
application is not serving a client, ReleaseObject also decrements the TOcApp object's 
internal reference count. The object will destroy itself when the count reaches zero. The 
destructor of TOcModule calls this function. 


See also TOcModule 


SetOption 

void SetOption(uint32 bit, bool state); 

Modifies the application's running mode flags. bit contains bit flags from the 
TOcAppMode enum. If state is true, SetOption turns the flags on. If state is false, it turns 
the flags off. You should never have to call this function because ObjectComponents 
always maintains the mode flags. 


See also TOcApp::IsOptionSet, TOcAppMode enum 


SetupWindow 

void SetupWindow(HWND frameWnd); 

Tells the TOcApp object what window to associate with the application. Usually 
frameWnd is the application's main window. Usually this function is called from the 
Setup Window function associated with the application's main window. 


TranslateAccel 

bool TranslateAccel(MSG far* msg); 

A container application adds TranslateAccel to its Windows message loop if it wants to 
make a DLL server's accelerator keystrokes available to the user during in-place editing. 
DLL servers require this cooperation because they do not have message loops of their 
own, as an .EXE server does. 


If you call TranslateAccel after the usual call to the Windows API TranslateAccelerator, 
then your own accelerators will have priority if they happen to conflict with the server's. 


msg holds a Windows message structure. The return value is true if the server translates 
the accelerator and false if it does not. 


UnregisterClass 

bool UnregisterClass(const string& progid); 

Notifies OLE when the application is no longer available to produce objects of a certain 
type. progid is the registered string that identifies a type of object. 


UnregisterClasses loops through all the documents the application registered and calls 
UnregisterClass for each one. The destructor of TOcApp calls UnregisterClasses. 


See also TOcApp::RegisterClass, TOcApp::RegisterClasses, TOcApp::UnregisterClasses 
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UnregisterClasses 

void UnregisterClasses(const TDocTemplate* ninead = --DocTemplateStaticHead); | 
Announces to the system that the application is no longer available for OLE interactions. 
tplHead points to the beginning of the application's list of document templates. 
ObjectWindows stores this list in the global variable DocTemplateStaticHead. 


UnregisterClasses loops through the list of document types and calls UnregisterClass for 
each one that has a registered progid. UnregisterClasses is called from the TOcApp 
destructor. 


Seealso progid registration key, TOcApp::RegisterClass, TOcApp. RegisterClasses, 
TOcApp::UnregisterClass —,, 


Protected constructor and destructor 


Constructor 
TOcApp(TOcRegistrar& registrar, uint32 options = ULONG_MAX, lUnknown* outer = 0, 

const TDocTemplate* tplHead = ::DocTemplateStaticHead); 
The constructor for a TOcApp object expands the application's message queue if 
necessary to accommodate OLE message traffic and builds the application's list of 
supported Clipboard formats. 


registrar is a registration object that over the command line. Create the registrar 
first. 


options is a set of application mode bit flags. The TOcApp object is usually created in the 
TComponentFactory callback function. The constructor's options parameter is the same as 
the callback's options parameter. 


outer points to the [Unknown interface of the outer object inside which the new 
application is asked to aggregate itself. 


tplHead points to the head of an application's list of document templates. The 
ObjectWindows Library stores an application's document template list in the global 
variable DocTemplateStaticHead. 


Destructor 
~TOcApp(); 
The TOcApp destructor notifies OLE that the application is no longer available. 


Usually the creation and destruction of an application's TOcApp object are managed by 
the TOcRegistrar object. 


See also TComponentFactory typedef, TOcRegistrar class, TOcApp::ReleaseObject 


Protected member functions 


ForwardEvent 

uint32 ForwardEvent(int eventld, const void far* param): 

uint32 ForwardEvent(int eventld, uint32 param = 0); 

Both forms send a WM_OCEVENT message to the application's main window. The 
eventId parameter becomes the message's wParam and should be one of the 
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OC_APPxxxx or OC_VIEWxxxx constants. The second parameter becomes the 
message's [Param and can be either a pointer (Form 1) or an integer (Form 2). Which 
form you use depends on the information a particular event needs to send in its /Param. 


Seealso WM_OCEVENT message, OC_APPxxxx messages, OC_VIEWxxxx messages, 
TOcRegistrar class 


ForwardEvent 

uint32 ForwardEvent(int eventld, const void far* param); 

uint32 ForwardEvent(int eventid, uint32 param = 0); 

Both forms send a WM_OCEVENT message to the application's main window. The 
eventid parameter becomes the message's wParam and should be one of the 
OC_APPxxxx or OC_VIEWxxxx constants. The second parameter becomes the 
message's [Param and can be either a pointer (Form 1) or an integer (Form 2). Which 
form you use depends on the information a particular event needs to send in its /Param. 


See also WM_OCEVENT message, OC_APPxxxx messages, OC ~VIEWXxxxx messages, 
TOcRegistrar class 
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ocfiocreg.h 


enum TOcAppMode 

The enumerated values of TOcAppMode represent flags that ObjectComponents sets to 
indicate an application's running modes. Some flags are set in response to command- 
line switches that OLE places on a server's command line. Others are set as the 
application registers itself. 


To determine whether a particular mode flag is set, call TOcApp::IsOptionSet or 
TOcModule::IsOptionSet. The TOcApp object holds the mode flags for each instance of the 
application. TOcModule simply queries the TOcApp. 


The enumerated values are bit flags and can be combined with the bitwise OR operator 
(|). Flags marked with an asterisk can differ for each instance of an application. 


Constant — What the Server Should D Do_ . 

oe Combine the RegServer, pare and Typelibb bits. 

amAutomation Register itself as single-use (one client only). Always accompanied by —Embedding. 

amDebug Enter a debugging session. 

amExeMode *Nothing. This flag is set to indicate that the server is running as an .EXE. Either the 
server was built as an .EXE, or it is a DLL that was launched by an .EXE stub and is 
running as an executable program. 

amExeModule Nothing. This flag is set to indicate that the server was built as a .EXE program. 

amEmbedding *Consider remaining hidden because it is running for a client, not for itself. 

amLangld Use the locale ID that follows this switch when creating registration and type 
libraries. (Useless without the —-RegServer or —TypeLib switch.) 

amNoRegValidate | Omit the usual validation check comparing the server's progid, clsid, and path to 
those registered with the system. The registrar object responds to this flag. 

amRegServer Register itself in the system registration database and quit. 

amRun Run its message loop. This is used by the factory callback function. 
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amServedApp *Avoid deleting itself (a client is using the application and holds a reference to it). 
amShutdown *When the TComponentFactory callback sees this flag, it should terminate the 
| application. 
amSingleUse *Register itself as a single-use (one client only) application. 
amTypeLib Create and register a type library. | 
amUnregServer Remove all its entries from the system registration database and quit. — 


See also TOcModule::IsOptionSet, TOcApp::IsOptionSet 


enum TOcAspect 

A container uses these values to request that objects in its documents be presented in 
particular ways. An object might be asked to show all its content, to show a miniature 
representation of its content, or an icon that represents the type of object it is. A server is 
not obliged to support all the possible aspects. 


The values are flags and can be combined with the bitwise OR operator (| ). 


asConten 


asThumbnail Show the content of the object shrunk to fit in a smaller space. 


asIcon Show an icon representing the type of object. 

asDocPrint Show the object as it would look if sent to the printer. 

asDefault Continue to use the last aspect specified. 

asMaintain Preserve the object's original aspect ratio. Do not alter the aspect ratio to fit the rectangle 


where the client chooses to show the object. 


See also 
TOcPart::Draw, ocrxxxx aspect constants 


TOcDialogHelpenum = __etocobjecth 


enum TOcDialogHelp 

The OC_APPDIALOGHELP event tells the container when the user clicks the Help 
button in a standard OLE dialog box. The /Param of the WM_OCEVENT message 
carries one of these values to indicate which dialog box the user has open. 


dhBrowse Insert Object dialog box Choose an object to insert. 

dhBrowseClipboard Paste Special dialog box Choose the data format for pasting an object. 
dhConvert Convert dialog box — Convert an object to work with a different server. 
dhBrowseLinks Links dialog box Update links to objects. 
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TOcDocument class 


dhChangelcon — Change Icon dialog box Used internally by Insert Object and Paste Special | 
dialog boxes. 

dhFileOpen File Open dialog box Choose a file to open. 

dhSourceSet Change Source dialog box Assign a new link source to a linked object. 

dhIconFileOpen File Open dialog box Confirm that the chosen file contains an icon resource. 

See also 


EvOcAppDialogHelp event handler, OC_APPxxxx messages, 
TOleFrame::EvOcAppDialogHelp, WM_OCEVENT message 


TOcDocument class ocflocdoc.h 


The primary responsibility of a TOcDocument is to save and load data in a compound 
file using hierarchically ordered storages. (A storage is a compartment within a file, just 
as a directory is a compartment on a disk.) By default the application's native data 
always goes in the document's root storage, but the application is free to create its own 
storages in the same file. TOcDocument creates new storages below the root as necessary 
for OLE objects that the user inserts into the compound document. The new storages 
take their names from the names of the objects they store. TOcView automatically 
assigns a unique string identifier to each new object. 


Both servers and containers can create objects of type TOcDocument. In the container, 
this object represents an entire compound document. In the server, it represents the data 
for a single OLE object. (The server's single OLE object can have other OLE objects 
linked or embedded in it.) 


A TOcDocument object manages the collection of TOcPart objects that are deposited in 
one of the container's documents. It does not draw the data on the screen. To do that, 
every TOcDocument needs a corresponding TOcView or TOcRemView object. An 
application can possess multiple pairs of associated document and view objects, one for 
each open document. 


A container creates a TOcView object to draw its compound document in the container's 
own window. Because the window where the server draws belongs to the container (it 
is a child of the container's window), the server must create a remote view object 
(TOcRemView) for each document. 


In spite of the similar names, TOcDocument and TOcView are not part of the 
ObjectWindows Doc/View model. The nature of OLE makes it useful to separate data 
from its graphical representation, and the terms document and view express that 
separation even outside of ObjectWindows. 


To execute its tasks, a TOcDocument must use the standard OLE interfaces IStorage and 
Stream. Usually it is not necessary to use these interfaces directly because 
ObjectComponents implements them for you in its undocumented TOcStorage and 
TOcStream classes. These classes are thin wrappers around standard OLE interfaces. The 
implementation of TOcDocument makes use of both objects. 
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TOcDocument class 


Form 1 


Form 2 


See also 
TOcRemView class, TOcView ies 


Public constructors and destructor 


Constructors 
TOcDocument(TOcApp& app, const char far* fileName = 0); 
Creates a new document object for the application and optionally assigns a file name for 


_ storing the document. A container uses this constructor for each document the user 


opens. 


TOcDocument(TOcApp& app, const char far* fileName, IStorage far* storagel) 


Creates a new document object for the application and assigns a particular file and 
storage object to hold the document. The container calls this constructor when opening 
an existing file. The server and the container each create their own TOcDocument object 
for the object they share, but both their objects point to the same file for storing the 
object. 


IStorage is the standard OLE storage interface. ObjectComponents implements this 
interface in its internal, undocumented TOcStorage class. It is usually not necessary to 
manipulate the [Storage interface or the TOcStorage class directly in an 
ObjectComponents application. 


Destructor 
~TOcDocument(); 
Destroys the TDocument object. 


Public member functions 


Close 

void Close(); 

A container calls TOcPart::Close for each object in the compound document to release its. 
servers. TOleDocument calls this function automatically when asked to close down. 


Seealso TOcPart::Close, TOleDocument class 


GetActiveView 

TOcView* GetActiveView(); 

Returns a pointer to the active view. TOcPart calls this method to Sonat changing 
focus among active parts. 


See also TOcDocument::SetActiveView 


GetName 

string GetName() const; 

Returns the name of the file where the document will be stored. ObjectComponents 
keeps track of the name in order to create links correctly. 


See also TOcDocument::SetName 
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GetParts © 

TOcPartCollection& GetParts(); 

Returns an object with information about all the parts in the document. Each part 
corresponds to a linked or embedded object. Create an iterator of type 
TOcPartCollectionIter to loop through the collection and extract information about 
individual parts. 


See also TOcPart class, TOcPartCollection class, TOcPartCollectionIter class 


GetStorage 
TOcStorage* GetStorage(); 
Returns the document file's root storage. 


See also TOcDocument::SetStorage 


LoadParts 

bool LoadParts(); 

Reads all the linked and embedded parts saved in a compound file. LoadParts does not 
necessarily load all the data from all the parts into memory immediately. The data is 
needed only if the object is visible. 


LoadParts returns true if all the parts are read successfully. If no file has yet been 
assigned to the document, then there is nothing to load and the function still returns 
true. (A document can acquire a file from its constructor, from SaveToFile, or from 
SetStorage.) 7 


See also TOcDocument public constructors and destructors, TOcDocument::SaveParts, 
TOcDocument::SaveToFile, TOcDocument::SetStorage 


RenameParts | 

void RenameParts(IBRootLinkable far* BLDocumentl); 

Call this whenever the name of the document file changes. RenameParts updates the 
internal name stored with each part so that other applications can still link to them 
correctly. 


IBRootLinkable is a custom OLE interface defined in the BOCOLE support library. 
Objects of type TOcView implement this interface, so it is usually not necessary to 
implement it yourself. Simply pass the document's view object to RenameParts. 


TOcView calls this function automatically if the view is renamed. 


Seealso TOcDocument::SetName, TOcView::Rename 


SaveParts 

bool SaveParts(IStorage* storage = 0, bool sameAsLoaded = true); 

Writes all the document's linked and embedded objects to the document's file. storage is 
the root storage in the file. A container's TOcDocument creates the storage object when 
the document is created or the first time it is saved. Find the object by calling GetStorage. 
A server gets the storage object from the container. It is usually not necessary to 
manipulate the storage object directly. 


sameAsLoaded should be true unless the name of the document file has changed since the 
last time the document was loaded or saved. 
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TOcDocument class 


Form 1 


Form 2 


SaveParts returns true if all the objects are successfully written to the file. 
LoadParts and SaveParts are called by the Open.and Commit methods in TOleDocument. 


See also TOcDocument::GetStorage, TOcDocument::LoadParts, 
TOcDocument::SaveToFile 


SaveToFile 

bool SaveToFile(const char far* newName); 

Saves the document in the file named by newName. Usually a container calls this 
function when the user chooses File | Save for an unnamed document or File |Save As 
for any document. SaveToFile creates a new storage object and then calls SaveParts. It . 
returns true if all the linked and embedded parts are successfully saved. 


See also TOcDocument::SaveParts 


SetActiveView 

void SetActiveView(TOcView* view); 

A TOcView object calls this method when it is activated so that the document can locate 
the active view. TOcDocument communicates only with the active view. The active view 
sends messages to the corresponding window, perhaps a TOleView window. This 
window is responsible for telling other windows about changes. 


Seealso TOcDocument::GetActiveView 


setName 

void SetName(const string& newName); 

Tells the document the name of the file where it will be stored. ObjectComponents 
needs to know the name in order to create links correctly. More specifically, SetName 
causes ObjectComponents to update the OLE moniker that a link server must provide. 


Seealso TOcDocument::GetName 


SetStorage 

void SetStorage(const char far* path); 

Creates a compound file using the name in path and assigns the root storage of the new 
file to be the root storage of the document. Usually a container calls this function when 
the user chooses File | Save for an unnamed document or File | Save As for any 
document. 


void SetStorage(IStorage* storage); 

Assigns storage to be the document's root storage. Usually a server calls this function 
when the container passes it an [Storage object. (An [Storage object implements the 
standard OLE interface Storage. Usually it is not necessary to manipulate this object 
directly.) 


Assigns the document a storage for writing its data. storage becomes the document's root 
storage. Each linked or embedded object gets its own substorage under the root storage. 


See also TOcDocument::GetStorage 
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TOcDragDrop struct 


TOcDragDrop struct __etocviewh 


Holds information that a view or a window needs in order to accept a drag and drop 
object. The OC_VIEWDRAG and OC_VIEWDROP messages carry a reference to this 
structure in their /Params. TOleView and TOleWindow process these messages for you, so 
you should not need to use TOcDragDrop directly unless you are programming without 
ObjectWindows. For examples of how to process OC_VIEWDRAG and 
OC_VIEWDROP messages, look at the source code for the EvOcViewDrag and 
EvOcViewDrop methods in TOleView and TOleWindow. 


See also 
OC_VIEWxxxx messages, TOleView::EvOcViewDrag, TOleView::EvOcViewDrop, 
TOleWindow::EvOcViewDrag, TOleWindow::EvOcViewDrop 


Public data members 


Initinfo 

TOclnitinfo far* InitInfo; 

When carried in an OC_VIEWDROP message, this field describes an object about to be 
dropped on the view. When carried in an OC_VIEWDRAG message, this field is zero. 


Seealso OC_VIEWxxxx messages, TOclInitInfo class 


Pos 

TRect Pos; 

The coordinates in Pos indicate the area of the view where the user has dropped an 
object. The position is given in device coordinates relative to the client area. 


Seealso TRect class 


Where 

TPoint Where; 

The coordinates in Where indicate the point on the view where the mouse released the 
object. The position is given in client area coordinates. 


Seealso TPoint class 


TOcDropAction enum ocflocobject.h 


enum TOcDropAction 

TOcApp::Drag uses these values to describe what actions are allowed and what actions 
actually occur during a drag and drop operation. The values are flags and can be 
combined with the bitwise OR operator (| ). 


daDropCopy Copy the object to the drop site. 
daDropMove Move the object to the drop site. 
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daDropLink Create a link to the object at the drop site 
daDropNone No action occurred. | 


See also 
TOcApp::Drag 


TOcFormatList class octiocview:h 


Manages a list of Clipboard formats that a paricuise view supports. 


TOcFormat, TOcFormatList, and TOcFormatListIter all work together to maintain the list 
of formats. TOcFormatList adds and deletes TOcFormat objects from the list. 
TOcFormatListIter enumerates the items in the list whenever the view needs to examine | 
them one by one. Because TOcView creates and maintains this list internally, it is usually 
not necessary for you to use any of these classes directly. 


When ObjectComponents receives your document registration table, it sees entries for 
each Clipboard format that the document receives or produces. From these entries, 
TOcView creates a list of objects of type TOcFormat, each object representing one format. 
The view needs this list to know when a Clipboard command or drag and drop 
operation can succeed. For example, if the user drags a bitmap over a view that accepts 
only text, TOcView knows the object cannot be dropped and adjusts the cursor 
accordingly. 


See also 
TOcFormat class, TOcFormatListIter class, TOcView class | 


Public constructor and destructor 


Constructor 
TOcFormatList(); 
Creates an empty list object. To insert items in the list, call the Add method. 


Destructor — 
~TOcFormatList(); 
Deletes all the items in the list. 


See also TOcFormatList::Add 
Public member functions 
Add 


int Add(TOcFormat* format); | 
Inserts a new Clipboard format item in the list. Returns 0 for failure and 1 for success. 


See also TOcFormatList::Clear 
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Clear 
void Clear(int del = 1); | 
Removes all the items from the list. If del is 1, Clear also deletes all the TOcFormat objects. 


Seealso TOcFormatList::Add, TOcFormatList::Detach 


Count 
virtual uint Count() const; 
Returns the number of items in the list. 


See also TOcFormatList::IsEmpty 


Detach 

int Detach(const TOcFormat* format, int del = 0); 

Removes one format item from the list. If del is 1, then Detach also deletes the TOcFormat 
object. 


See also TOcFormatList::Add, TOcFormatList::Clear 


Find 

unsigned Find(const TOcFormat* format) const; 

Searches the list for the object passed as format. If the object is found, then Find returns 
the object's position in the list. (The first position is 0.) If format is not in the list, Find 
returns UINT_MAX. 


IsEmpty 
int IsEmpty() const; 
Returns 1 if the list object currently contains no TOcFormat items and _0 if the list is not 


empty. 
Seealso T0OcFormatList::Count 


operator [] 

TOcFormat*& operator [(unsigned index)]; 

Retrieves a Clipboard format by its position in the list. If index is 1, for example, the [] 
returns the second item in the list. The order of items depends on the priority assigned 
to them when they are registered. 


Enumerates all the Clipboard formats that a particular view supports. 


TOcFormat, TOcFormatList, and TOcFormatListlter all work together to manage the list of 
formats. TOcFormatList adds and deletes TOcFormat objects from the list. 
TOcFormatListIter enumerates the items in the list whenever the view needs to examine 
them one by one. Because TOcView creates and maintains this list internally, it is usually 
not necessary for you to use any of these classes directly. 


When ObjectComponents receives your document registration table, it sees entries for 
each Clipboard format that the document receives or produces. From these entries, 
TOcView creates a list of objects of type TOcFormat, each object representing one format. 
The view needs this list to know when a Clipboard command or drag and drop 
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TOcFormatName class 


Form 1 


Form 2 


Form 1 


Form 2 


operation can succeed. For example, if the user drags a bitmap object over a view that 
accepts only text, TOcView knows the object cannot be dropped and acne the cursor 
accordingly. 


See also 
TOcFormat class, TOcFormatList class, TOcView class 


Public constructor 


Constructor | 
TOcFormatListiter(const TOcFormatList& collection) | 
Constructs an iterator to enumerate the Clipboard formats contained in collection. 


Public member functions 


Current 
TOcFormat* Current() const; 
Returns the format that the iterator currently points to. 


operator ++ 

TOcFormat* operator++(); | 

Returns the current format and then advances the iterator to point to the next format 
(postincrement). 


TOcFormat* operator++(int); 7 
Advances the iterator to point to the next format in the list and then returns that format 
(preincrement). 


operator int() 

operator int() const; 

Converts the iterator to an integer value in order to test whether the iterator has finished 
enumerating the collection. If parts remain unenumerated, the operator returns the 
iterator's current position in the list of parts. If the iterator has reached the end of the list, 
the operator returns zero. | 


Restart 
void Restart(); 
Resets the iterator to begin again with the first format in the list. 


void Restart(unsigned start, unsigned stop); 
Resets the iterator to enumerate a subset of the format list, beginning with he object at 
position start and ending with the object at position stop. 


TOcFormatName class #7 oct/ocapp.h 


TOcApp uses this class internally to hold the strings that describe a Clipboard data 
format such as text or bitmap. TOcApp displays these strings in standard OLE dialog 
boxes such as Paste Link. | 
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TOcFormatName class 


Every Clipboard format has three associated pieces of information: an ID value, a name 
string, and a result name. For standard formats, the ID is a constant such as CF_SYLK. 
The name string is a short name such as "Sylk." The result name is a longer string that 
tells the user what pasting this data produces—for example, "a spreadsheet." A 
TOcFormatName object holds all three values for one format. 


TOcApp makes a TOcNameList object to hold all the format names it needs. It loads 
descriptive strings into TOcFormatName objects and adds the objects one by one to its 
name list. Both objects are created and managed inside TOcApp. Usually you do not 
have to manipulate either of them directly. 


See also 
TOcApp class, TOcNameList class 


Public constructors and destructor 


Constructors 
TOcFormatName(); 
Constructs an empty format name object. 


TOcFormatName(char far* fmtName, char far* fmtResultName, char far* id = 0); 

Constructs a format name object and initializes it with three values that describe a 
Clipboard format. fmtName is the name of the format ("metafile"). fmtResultName 
describes what the user gets by pasting this format ("a Windows metafile picture"). id is 
the value that Windows assigns to identify the format (CF_METAFILEPICT) but 
expressed as a string of decimal digits ("3"). 


Destructor 
~TOcFormatName(); 
Releases the object. 


Public member functions 


Getld 
const char far* Getld(); 
Returns a pointer to the string that the system uses to designate the format. 


~ GetName 


const char far* GetName(); 
Returns a pointer to the name of the format. 


GetResultName 

const char far* GetResultName(); 

Returns the descriptive string that tells the user what pasting data of this format 
produces. 


operator == 
bool operator ==(const TOcFormatName& other); 
Returns true if other is the same object as this. 
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—  TOcInitHow enum | | ee | | 
TOcinitHowenum | - octlocobject.h_ 


enum TOclnitHow 

These values tell whether a container is to link or embed a new object it is receiving. The 
container passes this information to a TOcInitInfo object when it receives a new OLE 
object. 


eee | 
the server's document where the data actually resides. 


ihEmbed Embed the object. Copy the object's data directly into the container's document. 
ihMetafile Embed a static object that draws itself as a metafile. 
ihBitmap Embed a static object that draws itself as a bitmap. 


Seealso TOcInitInfo public constructors, TOcInitWhere enum 


TOcinitinfo class | a _ ocflocobject.h 


TOcInitInfo holds information that tells ObjectComponents how to create a new part. 
When the user pastes, inserts, or drops an object into a container, ObjectComponents 
creates a TOcInitInfo object, initializes it with information about the incoming OLE 
object, and passes the info object to the TOcPart constructor. The info object tells the part 
where to find its data and how to create itself. 


If you are using ObjectWindows, TOleView manages these details for you. If you are 
programming without ObjectWindows, you can find sample code for using TOcInitInfo 
objects in the TOleView methods that insert objects: look at the code for 
CmEditInsertObject and CmEditPasteSpecial. Look also at the code for TOcView::Drop. 


See also 
TOcPart Class, TOcView::Drop, TOleView::CmEditInsertObject, 
TOleView::CmEditPasteSpecial 


Public data members 


Container 

IBContainer far* Container; 

Container is the view object that is about to receive the shied IBContainer is an 
undocumented custom OLE interface defined in the BOCOLE support library and 
implemented in TOcView. The Container data member can hold an object of type 
TOcView. 


See also TOcView class 


Hicon 
HICON Hlcon; 
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HIcon holds the icon to draw if the user chooses the Display As Icon option from the 
Insert Object dialog box. The HIcon handle is actually a global memory handle to a 
metafile containing the icon. The Browse and BrowseClipboard functions in TOcApp 
handle the Insert Object dialog box for you, so usually you do not need to display the 
icon directly yourself. 


How 

TOclInitHow How; 

Tells whether the object should be linked or embedded when it is added to the 
document. 


Seealso TOcInitHow enum 


Storage 

[Storage far* Storage; 

Storage is the storage object in a compound file. The container provides the storage to 
hold data transferred from the server. [Storage is a standard OLE interface. 
ObjectComponents implements the [Storage interface in TOcStorage, so Storage usualy 
holds a TOcStorage object. 


Where 

TOcinitWhere Where; 

Tells where the server will place the object's data. For example, the server can choose to 
transfer data by placing it in a file, in a storage, or ina memory handle. 


Seealso TOcInitWhere enum 


Data 

IDataObject* Data; 

One of four data fields in an anonymous union, this field is used when Where is 
iwDataObject indicating that the server has created an OLE data object to transfer the 
data for the incoming object. Data points to the [DataObject interface on the server's data 
transfer object. ([DataObject is a standard OLE interface.) This is the normal transfer 
method for objects received from the Clipboard or through a drag-and-drop operation. 


Path 

LPCOLESTR Path; 

One of four data fields in an anonymous union, this field is used when Where is twFile 
indicating that the server has placed the data for the incoming object ina file. Path points 
to the name of the file where the data is stored. 


Cid 

BCID Cld; 

One of four data fields in an anonymous union, this field is used when Where is iwNew 
indicating that the incoming object is brand new, being freshly created. Cld is the class 
ID that the server registered for one of its document factories. It tells the server what 
kind of object to create. 


Seealso TOcApp::RegisterClasses, TOclinitInfo::Where 


Handle 
struct{ 
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HANDLE Data; 

uint DataFormat; 
} Handle; 
One of four data fields in an anonymous union, this structure is used when Where is 
iwHandle indicating that the server has placed the data for the incoming object in a 
memory handle. Data is the handle itself and DataFormat identifies a Clipboard format 
for the data i in the handle. | 


Public constructors 


TOcinitinfo | 

[BContainer far* Container; 7 
Container is the view object that is about to receive the object. [BContainer is an 
undocumented custom OLE interface defined in the BOCOLE support library and 


implemented in TOcView. The Container data member can hold an object of type 
TOcView. 


See also TOcView class 


TOcinitinfo 
-Form1 = TOclnitInfo(IBContainer far* container); 
Use Form 1 when invoking the server to create a new object from scratch—for example, 


when processing the Insert Object command. The new part will be embedded, not 
linked. 


Form 2  TOclnitInfo(TOcinitHow how, TOcinitWhere where, IBContainer far* container); | 
Use Form 2 when creating a part to hold an object that already exists—for example, 
when loading a part from a storage in a compound document. how tells whether the 
object will be linked or embedded. where tells what medium the server will use to 
transfer data from the existing object. 


Both forms of the constructor create a TOcInitInfo object for placing anew partin ~ 
container. container is the view that will hold the new part. IBContainer is a custom OLE 
interface defined in the BOCOLE support library and papiomente in TOcView. 
container can be an object of type TOcView. 


Public member functions 


ReleaseDataObject 
uint32 ReleaseDataObject(); 

If the TOcInitInfo object holds a Sonics to the data object from which the new part is 
about to be created, then ReleaseDataObject decrements the data object's reference count. 
Call this when you are through with the data object. 


Seealso TOclInitInfo: ‘Data 


TOcinitWhere enum 7 ocflocobject.h- 


enum TOclnitWhere 


620 ObjectWindows Reference Guide 


TOcInvalidate enum 


These values tell where the data for an object resides. A container passes this 
information to a TOcInitInfo object when it receives a new OLE object for linking or 
embedding. The server can choose any of several available channels for transferring the 


data in the object. 
Constant ee Meaning — 
iwFile The server passes the data ina aidick file. 
iwstorage The server passes the data in a storage object (part of a compound file). 


iwDataObject The server passes the data in a data transfer object, one that supports the standard 
IDataObject OLE interface. (Objects transferred through the Clipboard or by dragging 
support this interface. TOcInitInfo holds a pointer to the interface.) 


iwNew The server will be asked to create a new object. 
iwHandle The server passes a memory handle for the data. 


Seealso TOclInitInfo public constructors, TOcInitHow enum 


TOclInvalidate enum ocflocobject.h 


enum TOclnvalidate 

Functions that invalidate an object use these enumeration values to indicate whether the 
data in the object has changed or the appearance of the object has changed. It is possible 
for the data in an object to change without invalidating the view of the object. For 
example, if the object is drawn as an icon, then editing the data probably does not call 
for an update to the view. If both the data and the view change, then combine both flags 
with the bitwise OR operator (1 ). 


If the view is invalid, the object needs to be redrawn. If the data is invalid, then the object 
needs saving. (It is not necessary to save the object right away. invData simply indicates 
that the object is dirty and needs to be saved before the document is closed.) 


invData | The data inan object has changed and should be updated in the eoniainen 


invView The appearance of an object needs to change and should be updated in the container. 


Seealso TOcRemView::InvalidateTOc, TOleView::InvalidatePart, 
TOleWindow::InvalidatePart 


TOcMenuDescr struct ocflocapp.h 


The menu descriptor structure is used when merging the menus of a container and 
server for in-place editing. The structure holds a handle to a shared Windows menu 
object and a count of the number of drop-down menus in each group. 


If you are using ObjectWindows, use the information in the structure to construct a 
TMenuDescr object for the other application. To merge two menus, call 
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TMenuDescr: iiss If you are not using ObjectWindows, call the Windows API 
routines such as InsertMenu to place your own commands in the shared menu. 


The following messages carry a TOcMenuDescr struct in their /Params: 
OC_APPINSMENUS, OC_APPMENUS, and OC_VIEWINSMENUS. The 
ObjectWindows OLE-enabled window and view classes process these messages for 
you. Unless you are programming without ObjectWindows, you usually will not have 
to use TOcMenuDescr directly. For examples of how to process the messages, see the 
source code for the relevant event handlers in TOleView, TOleWindow, TOleFrame, and 
TOleMD IFrame. 


See also 
OC_APPxxxx messages, OC_VIEWxxxx messages, TMenuDescr class 


Public data members 


HMenu 

HMENU HMenu; 

Holds a handle to the shaned menu. The handle is valid only while the menu is 
constructed. Do not store it for later use. 


Width 

int Width[6]; 

The Width array contains the number of pop-up menus in each menu group. The 
groups, in order, are File, Edit, Container, Object, Windows, and Help. 


The array is meant to help you construct a TMenuDescr object. The numbers it holds 
control how the menu is merged. 


See also TMenuDescr public constructors and destructors 


TOcModule class _ | ocflocapp.h 


TOcModule is a mix-in class for deriving OLE-enabled spnlieation classes. Any 

_ ObjectComponents application that supports linking and embedding should derive its 

_ application class from both TApplication and TOcModule. The ObjectComponents 
module class coordinates some basic housekeeping chores related to registration and 
memory management. It also holds a pointer to the TOcApp object that connects your 
application object to OLE through ObjectComponents. Allowing TOcModule to do this 
work also makes it easy to use the same code for both .EXE and .DLL versions of the 
same server. 


See also 
TApplication class, TOcApp class 
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Public constructor and destructor 


Constructor 
TOcModule(); 
Builds a TOcModule. After creating a TOcModule object, you need to call Oclnit. 


Destructor 

~TOcModule(); 

Releases the TOcApp object. An application that derives from TOcModule does not need 
to call the TOcApp::ReleaseObject method when it closes down. (Never call delete to 
destroy a TOcApp object, either.) 


See Also TOcModule::OcInitTOcModuleOclInit 


Public member functions 


GetRegistrar | 
TRegistrar& GetRegistrar(); 
Returns the application's registrar object. Be sure to call Oclnit first. 


Seealso TOcModule::Ocinit, TRegistrar class 


IsOptionSet 

bool IsOptionSet(uint32 option) const; 

Returns true if the command-line flag indicated by option is set and false if it is not. The 
registrar sets the flags for you when it interprets OLE-related switches on the 
application's command line. The possible values for option are enumerated in 
TOcAppMode. 


See also TOcAppMode class, TOcRegistrar class 


Ocinit 

void Oclnit(TOcRegistrar& registrar, uint32 options); 

Initializes ObjectComponents support for the code module. This call causes 
ObjectComponents to create the TOcApp connector object that attaches the application 
to the OLE system. Always call OcInit right after constructing the module object. 


registrar is the application registrar object. It must be created before you call OclInit. 


options is a set of bit flags describing command-line options set for this instance of the 
program. To test for particular options, call IsOptionSet. The possible option flags are 
defined in TOcAppMode. | 


Seealso TOcApp class, TOcAppMode enum, TOcModule::IsOptionSet, 
TOcModule::IsOptionSet,, TOcRegistrar class 


Public data members 


OcApp 
TOcApp* OcApp; 
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TOcNameList class 


Holds the TOcApp object that is the ObjectComponents partner object for your 
TApplication-derived class. This member is initialized when you call OclInit. 


 Seealso TOcApp class, TOcModule::OcInit 


OleMalloc 

TOleAllocator OleMalloc; | 

Sets up an allocator object that initializes the OLE system and sets up the memory 
allocator. OLE allows each program to set up a memory manager for OLE to use when 
allocating and de-allocating memory on behalf of that application. 


TOcModule simply chooses the default allocator. If you have unusual memory 
management needs and want to supply your own custom memory allocator, set its 
IMalloc interface in OleMalloc::Mem. 


Seealso TOleAllocator class, TOleAllocator::Mem 


TOcNameList class ocflocapp.h 


TOcApp uses this class internally to manage a collection of TOcFormatName objects. Each 
format name object holds three strings that describe a Clipboard data format such as text 
or bitmap. TOcApp displays these strings in standard OLE dialog boxes such as Paste 
Link. | 

The list of format names is created and managed inside TOcApp. Usually you do not 
have to manipulate the list directly. To put your own custom formats in the list, 
however, you do have to register them. See TOcApp::Add UserFormatName for more 
information about setting up custom formats. | 


Standard Windows Clipboard formats are always added to the list for you. The name | 
and result strings for standard formats are defined in OLEVIEW.RC. To localize the 
strings, edit this file. (Standard formats do not have an identifier string. Instead they 
have a registration number, such as CF_TEXT.) 


See also 
TOcApp class, TOcApp::AddUserFormatName, TOcFormatName class 


Public constructor and destructor 


Constructor 
TOcNameList(); | 
Constructs a name list containing no items. To insert names in the list, call Add. 


Destructor 
~TOcNameList(); 
Destroys the list and the objects in the list. 


~  Seealso TOcNameList::Add 
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Form 2 


TOcNameList class 


Public member functions 


operator [] 

TOcFormatName*& operator|](unsigned index); 

Returns the item at position index in the list of format name objects. The first object is at 
index 0. If index points past the end of the list, the function throws a precondition 
exception. 


TOcFormatName* operator[](char far* id); 
Returns the format name object whose format ID string matches id. The return value is 0 
if no match is found. 


Seealso TOcFormatName 


Add 
int Add(T OcFormatName* name); 
Inserts the object name into the list. Returns 1 for success and 0 for failure. 


Seealso TOcNameList::Clear, TOcNameList::Detach 


Clear 
void Clear(int de! = 1); 
Empties the list. If del is 1, Clear also deletes each object in the list. 


Seealso TOcNameList::Add, TOcNameList::Detach 


Count 
virtual uint Count() const; 
Returns the number of items in the list. 


Seealso TOcNameList::IsEmpty 


Detach | 

int Detach(const TOcFormatName* name, int del = 0); | 

Removes the single object name from the list. If del is 1, Detach also deletes the object 
name. 


Seealso TOcNameList::Clear, TOcNameList::Add 


Find 

unsigned Find(const TOcFormatName* name) const; 

Searches the list and returns the position of name. If the name object is not in the list, Find 
returns UINT_ MAX. 


IsEmpty 
int IlsEmpty() const; 
Returns 1 if the list currently contains no items and 0 if it contains at least one item. 


Seealso TOcNameList::Count 
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TOcPartclass  ————————_setfocpart.h 


Form 1 


Form 2 


Base class 

TUnknown 

A TOcPart object represents a linked or embedded object in a document. It represents | 
the linked or embedded object as the container sees it. From the server's side, the same 
linked or embedded OLE object has two parts: data (TOcDocument) and a graphical 
representation of the data (TOcRemView). TOcPart manages a site in the container's 
document where a server places an OLE object. 


_ TOcPart isa COM object and implements the [Unknown interface. 


See also 
TOcDocument class, TOcPartCollection class, TOcRemView class, TUnknown class 


Public constructors 


Constructors 

TOcPart(TOcDocument& document, TOclnitinfo far& initInfo, TRect pos, int id = 0); 

document is the container's TOcDocument object representing the compound document 
that will hold the newly created part. initInfo contains information about the object being 
inserted. It is usually obtained during a paste, drop, or insertion operation. The 
coordinates in pos designate the area where the new object will be drawn. id is any 
arbitrary unique integer used to distinguish this object from others in the same 
document. If id is 0, TOcPart generates a new ID automatically. 


TOcPart(TOcDocument& document, const char far* name); 
document is the same as for Form 1. The name string is the name of a linked or embedded 


part. The second form is used when loading a part from a compound document. The 


name of the part is also the name of the storage where the part was written. 


Both constructors expect to receive the container's own TOcDocument object. This 
represents the compound document where the new object will be placed. 


See also TOcDocument class, TOcInitInfo class, TOcPart::Delete, TRect class 


Public member functions 


operator == 

bool operator==(const TOcPart& other); 

Returns true if other is the same TOcPart as this. This operator is defined for the use of 
the TOcPartCollection class. 


Activate | 

bool Activate(bool activate); | 

If activate is true, this function activates the part by asking the server to execute its 
primary (or default) verb for the object. If the default verb is Edit, for example, Activate 
initiates an in-place editing session. If activate is false, then this function deactivates an 
in-place editing session. 


626 ObjectWindows Reference Guide 


TOcPart class 


Activate returns true if the server is able to execute the command. 
Seealso TOcPart::IsActive, TOcPart::;Open 


Close 

bool Close(); 

Disconnects the embedded object from its server. Returns true if the server closes 
successfully. 


Delete 

void Delete(); 

Delete is used when the user selects an embedded object and presses the Delete key (or 
does a cut operation). It first calls Close to disconnect the container from the embedded 
object. Then it releases the reference to the embedded part. 


Seealso TOcPart::Close 


Detach 

int Detach(); 

Separates a part from its document. Call Detach before cutting a part to the Clipboard, 
for example. 


DoVerb 

bool DoVerb(uint whichVerb); 

Tells the server to execute one of its commands on the part. A verb is usually an action 
such as Edit or Play. One server can support several verbs, and whichVerb identifies a 
particular verb by its ordinal value. (The first verb, the primary or default verb, is zero.) 
DoVerb returns true if the server is able to complete the requested action. Executing a 
verb can cause the part to become activated. 


See also TOcPart::EnumVerbs 


Draw 
bool Draw(HDC dc, const TRect& pos, const TRect& clip, TOcAspect aspect = asDefault); 
Draws the part on the screen. If the part has not yet been loaded, Draw loads it first. 


dc is a Windows device context where the part is to be drawn. The coordinates in pos tell 
where in the window to place the part. The clip rectangle designates an area outside of 
which the server cannot draw. clip and pos can be the same. If clip describes an empty 
rectangle, then the server can draw anywhere. aspect controls how the data were 
presented—as an icon, for example. 


See also TOcAspect enum, TRect class 


EnumVerbs 

bool EnumVerbs(const TOcVerb& verb); 

Call EnumVerbs to find out what verbs the server supports for a particular part. Each call 
to EnumVerbs places another verb in the verb parameter. When all the server's verbs 
have been enumerated, EnumVerbs returns false. | 


TOleWindow calls EnumVerbs in order to place verbs for the active object on the 
container's Edit menu. 
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GetName 
LPCOLESTR GetName(); 

Returns the string that identifies the part. Every part in a document has a different 
name. ObjectComponents creates the names for you automatically by incrementing an 
internal ID number for each new part. 


Seealso TOcPart::GetNameLen, TOcPart::Rename 


GetNameLen 

int GetNameLen(); 

Returns the number of characters in the name string that identifies the part. The count 
does not include the terminating null character. 


See also TOcPart::;GetName, TOcPart::Rename 


GetPos 

TPoint GetPos() const; 

Returns the part's position within its container document. The position specifies the 
part's upper left corner in client area coordinates. The coordinates take into account any 
scaling set for the TOcView object that holds the part. 


See also TOcPart::GetRect, TOcPart::GetSize, TOcPart::SetPos, TPoint class 


GetRect 

TRect GetRect() const; 

Returns the rectangle that bounds the i image of the part in the container's client area. The 
position of the rectangle is given in client area coordinates. 


Seealso TOcPart::GetPos, TOcPart::GetSize, TOcPart::UpdateRect, TRect class 


GetServerName 

LPCOLESTR GetServerName(TOcPartName partName); 

Asks OLE for the name of the object or of the object's server, depending on the value of 
partName. A container might want to display this information in its title bar. 


In the current implementation of ObjectComponents, this function is not used. The 
TOcView object automatically updates the container window title. — 


See also TOcPartName enum. 


GetSize 

TSize GetSize() const; 

Returns the size of the part's image in the container document. The fields of the return 
value give the width and height of the part in client area coordinates. If there is scaling, 
the coordinates take that into account. 3 | 


Seealso TOcPart::GetPos, TOcPart::GetRect, TOcPart::SetSize, TSize class 


IsActive 
bool IsActive() const; 
Returns true if the part is currently active and false if it is not. 


Seealso TOcPart::SetActive 
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Form 1 


Form 2 


Note 


TOcPart class 


IsLink 

bool IsLink() const; 

Returns true if the part represents a linked OLE object and false if it represents an 
embedded OLE object. A container might use this method to distinguish visually 
between linked and embedded objects. For an example, look at the source code for 
TOleWindow::Paint Parts. 


IsSelected 

bool IsSelected() const; 

Returns true if the part is currently selected and false if it is not. This function is 
frequently called in loops that process all the selected objects in a document. For 
example, when TOleView paints the parts in a document, it calls IsSelected for each one to 
determine where to paint selection boxes. 


Selection state information is maintained entirely in TOcPart and does not affect the 
OLE object itself. 


Seealso TOcPart::Select 


IsVisible 
bool IsVisible() const; 
Returns true if the part is currently visible and false if it is hidden. 


bool IsVisible(const TRect& logicalRect) const; 

Returns true if the part is currently visible within the given logicalRect area of the 
container's window. Returns false if the part is not visible, perhaps because the user has 
scrolled to another part of the document. 


Seealso TOcPart::SetVisible 


Load 
bool Load(); 
Initializes a TOcPart object with information read fom a storage. 


See also TOcPart::Save 


Open 

bool Open(bool open); 

If Open is true, the Open command invokes the server to initiate an out-of-place editing 
session. More specifically, it asks the server to execute its Open verb. If Open is false, the 
command tells the server to hide its open editing window but does not end the session. 
Open returns true for success. If the server does not support editing, Open returns false. 


TOcPart::Close is not the opposite of TOcPart::Open. To terminate editing, pass false to 
Open. 


Seealso TOcPart::Activate 


Rename 

void Rename(); 

Causes the part to update the internal name that ObjectComponents generates to 
distinguish the parts in a document. Call Rename whenever you rename the document's 
file. OLE uses the object's name when creating links, so the object name must accurately 
reflect the file name in order for links‘ to work. 
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Form 1 


Form 2 


Seealso TOcPart::GetName, TOcPart::GetNameLen 


Save 
bool Save(bool sameAsLoaded = true); 


Causes the part to write itself into the document's file stream. If sameAsLoaded is true, 


then the part saves itself in the same storage where it was last written. Setting 
sameAsLoaded to false causes the part to create a new storage for itself under the 
document's new root storage. Usually sameAsLoaded should be true in response to a 
File |Save command and false in response to File | Save As. 


(A storage is a compartment within a compound file. ObjectComponents manages the 
storages for you. Usually you do not have to give explicit instructions about where to 
store parts.) 


bool Save(IStorage* storage, bool sameAsLoaded, bool remember); 
The second form accepts a pointer to an [Storage interface, allowing you to control where 


_ the object is written. sameAsLoaded is the same as in Form 1. remember tells the part 


whether or not to remember the object in storage. When saving a part to its usual file, 
you typically want it to remember its own storage. When copying a part, on the other 
hand, you typically want the part to keep its original storage object, not the one where 
you are saving the copy. When saving a copy to a a for the Clipboard, for example, 
remember should be false. 7 


Seealso TOcPart::Load 


Select 

void Select(bool select); | 

Tells the part whether or not it is currently selected. Make select true to select the part 
and false to deselect it. The user selects objects in order to perform operations on them. 
For example, the user selects an object before copying it to the Clipboard. When 
TOleView paints its parts, it queries each one and draws a selection box around any that 
the user has selected. 


Seealso TOcPart::IsSelected 


SetActive 

void SetActive(); | 

Synchronizes an internal flag with the object's actual state, active or inactive. Usually 
you should not have to call this function. To make a part active, call TOcPart::Activate 
instead. | 


Seealso TOcPart::Activate, TOcPart::IsActive 


SetHost 

bool SetHost(IBContainer far* container); 

Moves the part from one container to another. container can be an object of type TOcView 
(or one derived from TOcView). It designates the view that receives the part. SetHost is 
not usually called from within the application. 


IBContainer is a custom interface defined within the ed eupeom library. TOcView | 
implements this interface. 
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SetPos 

void SetPos(const TPoint& pos); | 

Sets the part's position within its container document. The position specifies the part's 
upper left corner in pixels measured from the upper left corner of the container's client 
window. If there is scaling, the coordinates take that into account. 


See also TOcPart::GetPos, TOcPart::SetSize, TOcPart::UpdateRect, TPoint class 


SetSize 

void SetSize(const TSize& size); 

Sets the size of the part's image in the container document. size sets the width and height 
of the part in client area coordinates. The coordinates take into account any scaling set 
for the TOcView object that holds the part. 


Seealso TOcPart::GetPos, TOcPart::SetSize, TOcPart:: UpdateRect, TSize class 


SetVisible 
void SetVisible(bool visible); 
Shows or hides the part, according to the value of visible. 


Seealso TOcPart::IsVisible 


Show 

bool Show(bool show); | 

Makes the part visible. Show is used to ask the Link Source to show itself in the container 
window. If show is false, the part hides itself. The return value is true for success. 


Seealso TOcPart::IsVisible 
UpdateRect 
void UpdateRect(); 


Sets the part to a new rectangle when its size or position changes. Called by SetPos and 
SetRect. 


See also TOcPart::GetRect, TOcPart::SetPos, TOcPart::SetSize 


Protected destructor 


Destructor 
~TOcPart(); 
Destroys the TOcPart object. 


TOcPartCollection class ocflocpart.h 


Manages a set of TOcPart objects. Every TOcDocument creates a part collection object to 
maintain the set of OLE objects linked or embedded in the document. The part collection 
object adds parts, deletes parts, finds them, counts them, and generally helps the 
document keep track of what it has. 


Because TOcDocument contains a part collection object, usually you do not have to create 
or manipulate the collection directly yourself. 
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_ See also 2s 
TOcPart class, TOcPartCollectionIter class 


Public constructor and destructor 


_ Constructor 
TOcPartCollection(); 
Creates an empty collection. Call Add to insert parts in the collection. 


Destructor 
~TOcPartCollection(); 
Releases all the servers that supply the linked or embedded juece 


Public member functions 


Add 
int Add(TOcPart* const& part); 
Adds a new part to the collection. Returns 1 for success and 0 for failure. 


Seealso ‘TOcPart class 


Clear 

void Clear(); 

Disconnects all the parts in the collection from their servers, removes them from the 
collection, and releases them. Tells OLE that this collection has no further need for the 
servers. 


Count 
virtual unsigned Count() const; | 
Returns the number of parts currently in the collection. 


Detach | 

int Detach(TOcPart* const& part, int del = 0); 

Removes part from the collection. If del is nonzero, then Detach also releases TOcPart 
object. If the part's internal reference count reaches zero as a result, the part deletes itself. 
Returns 1 for success and 0 for failure. 


See also TOcPart class 


Find 
unsigned Find(TOcPart* const& part) const; 


Searches for part and returns its position in the collection. If part is not in the collection, 
Find returns UINT_MAX. 


~Seealso TOcPart class 
IsEmpty 
int IsEmpty() const; 


Returns true if the collection currently contains no objects and false if it does contain at 
least one object. 
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Locate 

TOcPart* Locate(TPoint& point); 

Returns the part object visible at a particular point on the screen. The numbers in point 
are interpreted as logical coordinates. If no part in the collection occupies the given 
point, Locate returns 0. 


See also TPoint class 


SelectAll 

bool SelectAll(bool select = false); 

Sets the selection state of all the parts in the collection. If select is true, SelectAll selects 
them all. If select is false, it deselects all the parts. The user can perform actions (such as 
dragging, deleting, and copying) that affect all the selected objects. 


The container conventionally marks selected objects by drawing a rectangle with 
grapples (handles for moving the rectangle) around each of them. The TOleWindow class 
does this automatically in ObjectWindows programs. 


TOcPartCollectionlter class octlocpart.h 


Form 1 


A part collection iterator enumerates the objects embedded in a compound document. 


A compound document can contain many linked and embedded objects. Within the 
container, each object is represented by an object of type TOcPart. To manage all the 
parts it contains, TOcDocument creates a collection object of type TOcPartCollection. The 
collection object takes care of adding and deleting members of the collection. In order to 
walk through the current list of its parts, TOcDocument also creates a part collection 
iterator. An iterator basically points to an element in the collection. You can increment 
the iterator to walk through the list of objects. The iterator signals when it reaches the 
end (the ++ operator returns 0). 


Together the collection and its iterator give the document much flexibility in managing 
its objects. 


See also 
TOcPart class, TOcPartCollection class 


Public constructor 
Constructor 


TOcPartCollectioniter(const TOcPartCollection& coll); 
Constructs an iterator to enumerate the objects contained in the collection coll. 


See also TOcPartCollection class 


Public member functions 


operator ++ 
TOcPart* operator++(int); 
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Form 2 


Form 1 


Form 2 


Returns the current part and then advances the iterator to point to the next part 
(postincrement). 


TOcPart* operator++(); | | 
Advances the iterator to point to the next part in the list and then returns that part 


(preincrement). 


Current 
TOcPart* Current() const; 
Returns the part that the iterator or currently points to. 


operator int() 

Operator int() const; | 

Converts the iterator to an integer value in order to test whether the iterator has finished 
enumerating the collection. Returns zero if the iterator has reached the end of the list 
and a nonzero value if it has not. 


Restart 
void Restart(); | 
Resets the iterator to begin again with the first part in the document. 


void Restart(unsigned start, unsigned stop); 
Resets the iterator to enumerate a partial range of objects in Ke document, beginning 
with the object at position start in the list and ending with the object at position stop. 


TOcPartName enum ocflocobject.h 


enum TOcPartName | 
When a container asks the server for the name of a part, it might want any of several 
possible answers. These values indicate which name the container wants to see. 


pnLong The string the server registered as the description for this type of object. 


pnShort The string the server registered as the progid for this type of object. 
pnApp _ The string the server registered as the description for the server application as a whole. 


See also 
description registration key, progid registration key, TOcPart::GetServerName 


TOcRegistrar class _ ocflocapp.h 


Base class 

TRegistrar | 

TOcRegistrar manages all the registration tasks for an application. It processes OLE- 
related switches on the command line and records any necessary information about the 
application in the system registration database. If the application is already registered in 
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the database, the registrar confirms that the registered path, progid, and clsid are still 
accurate. If not, it reregisters the application. 


Every ObjectComponents application needs to create a registrar object. If your 
application supports linking and embedding, then create a TOcRegistrar object. If your 
application supports automation but not linking and embedding, then you should 
create a TRegistrar object instead. TOcRegistrar extends TRegistrar by connecting the 
application to the BOCOLE support library interfaces that support linking and 
embedding. 


An application's main procedure usually performs these actions with its registrar 
e Construct the registrar, passing it a pointer to the application's factory callback. 


¢ Call IsOptionSet to check for options that might affect how the application chooses to 
start (for example, remaining invisible if invoked for embedding. 


e Call Run to enter the program's message loop. 


TOcRegistrar inherits both IsOptionSet and Run from its base class, TRegistrar. 


See also 
clsid registration key, path registration key, progid registration key, TRegistrar class 


Public constructor and destructor 


Constructor 


TOcRegistrar(TRegList& reginfo, TComponentFactory callback, string& cmdLine, 
HINSTANCE hinst = _hinstance); 
regInfo is the application registration structure (conventionally named appReg). 


callback is the factory callback function that ObjectComponents invokes when it is time 
for the application to create an object. An ObjectWindows program can use the 
TOleFactory class to implement this callback. 


cmdLine holds the command line string that invoked the application. 


hInst is the application's instance. 


Destructor 
~TOcRegistrar(); 
Destroys objects the registrar uses internally. 


See also T?ComponentFactory typedef, TOleFactory<> class 


Public member functions 


BOleComponentCreate 

HRESULT BOleComponentCreate(|Unknown far* far* retlface, [Unknown far* outer, BCID idClass); 
Calls the BOCOLE support library to create one of the helper objects that 
ObjectComponents uses internally. Usually you do not need to call 
BOleComponentCreate yourself. 
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__retIface receives an interface to the requested component. 


outer is the [Unknown interface of the outer object that you want the new component to 
become a part of. — 


idClass identifies the particular component you want to create. The possible values are 
defined as cidBolexxxx constants in ocf/boledefs.h. 


The return value is an OLE result, either HR_OK for success or HR_ FAIL for pala 


See also HR _ xxxx result macros 


CreateOcApp 

void CreateOcApp(uint32 options, TOcApp*& ret); 

Creates the connector object that attaches an application to OLE. options is a set of bit 
flags indicating the application's running mode. The possible option flags are defined in 
TOcAppMode. ret is where CreateOcApp places a pointer to the newly created TOcApp 
connector object. 


CreateOcApp is called during TOcModule::OcInit. You shouldn't have to call it directly 
_ yourself. 


‘The purpose of CreateOcApp is to shield you from the details of the TOcApp connector 
object. TOcApp is closely tied to the implementation of ObjectComponents, and the 
details of initializing an OLE session are subject to change. | 


See also TOcApp class, TOcAppMode enum, TOcModule::OcInit 


GetAppDescriptor 

TAppDescriptor& GetAppDescriptor(); 

Returns the application descriptor. ObjectComponents uses an application descriptor 
internally to hold information about a module. (A DLL gets an application descriptor of 
its own.) T’AppDescriptor is undocumented because it is used only internally and is 
subject to change. The registrar classes, TOcRegistrar and TRegistrar, are the supported _ 
interfaces to the application descriptor. The registrar constructs the descriptor and most 
of its member functions call descriptor functions to perform the work. 


Usually you will not need to call this method yourself. 


Protected member functions 


CanUnload 

bool CanUnload(); 

Returns true if the application is not currently serving any OLE clients and false 
otherwise. 


GetFactory 

void far* GetFactory(const GUID& clsid, const GUID far& iid); 

Returns a pointer to the factory interface for creating the type of object indicated by clsid. 
iid names the particular interface you want to receive. If the registrar is unable to find an 
ud interface for clsid objects, it returns zero. 
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ObjectComponents calls a DLL's GetFactory member every time a new client loads the 
DLL. Usually you do not need to call GetFactory yourself. 


LoadBOle 

void LoadBOle(); 

Loads and initializes the ObjectComponents support library (BOCOLE.DLL). LoadBOle 
throws a T’XObj]Comp exception if it cannot find BOCOLE.DLL, or if the installed version 
is not compatible with the application's version of the library. 


TOcRemView class ocflocremvie.h 


Base class 

TOcView 

A linking and embedding server creates a remote view object in order to draw its OLE 
object in the container's window. TOcRemView only draws the object. To load and save 
the data in the object, the server also needs to create a TOcDocument object. The 
document and the remote view together represent an OLE object as the server sees it. 


The container creates a TOcPart object for every OLE object it receives. The container's 
part object communicates with the server's document and view objects through OLE. 
The part tells the server's view when and where to draw the object. It tells the server's 
document when and where to load or save the object. 


Do not confuse the two kinds of views, TOcView with TOcRemView. A container creates 
a single view (TOcView) for its compound document. This view can contain parts 
received from other applications. Each part draws itself by invoking a remote view from 
its server. Containers create TOcView objects and servers create TOcRemView objects. (A 
TOcRemView object can become a container also, however, if the user embeds objects 
within objects.) 

In spite of the similar names, TOcDocument, TOcView, and TOcRemView are not part of 
the ObjectWindows Doc/View model. The nature of OLE makes it beneficial to separate 


data from its graphical representation, and the terms document and view express that 
separation even outside of ObjectWindows. 


TOcRem View is a COM object and implements the [Unknown interface. 


See also 
TOcDocument class, TOcView class 


Public constructor 


Constructor 

TOcRemView(TOcDocument& doc, TRegList* regList = 0, |Unknown* outer = 0); 

A remote view is always associated with a TOcDocument object. The document loads 
and saves data in an OLE object and the remote view draws the data in the container's 
window. In both forms of the constructor, doc is the document to associate with the 
view. That means the document must always be created first. 
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| TOcRemView class 


Also, in both forms regList is a document registration table. A server that creates 
different kinds of objects needs several document registration tables, one for each type. 
The regList parameter determines the type of object that the view represents. outer points 
to the [Unknown interface of a master object under which the new object is asked to 

aggregate itself. | 


Registration tables are built with the BEGIN_ REGISTRATION and 
-END_REGISTRATION macros. 


The destructor for TOcRemView is pave ObjectComponents releases the object when 
it is no longer needed. 


See also BEGIN REGISTRATION 1 macro, TAutoObject class, TOcDocument class 


Public member functions 


Copy 
virtual boo! Copy(): 


Copies the object to the Clipboard. Returns true for success. 


EvClose 

virtual void EvClose(); | 
The application's remote view window calls this function when it closes. EvClose 
disconnects the view from any parts displayed in it. 


GetContainerTitle 

virtual LPCOLESTR GetContainerTitle(); 

Asks the container for its name. The server usually cnaivales this string in its own title 
bar during out-of-place editing (when the user edits a linked or embedded object in the 
server's own window, not in the container's). 


GetinitialRect 
void GetinitialRect(); 
Requests the initial size and position of the area where the server can draw its object. 


The function initializes Extent, a protected data member that TOcRemView inherits from _ 
TOcView. : 


Seealso TOcView::Extent 


Invalidate 

void Invalidate(TOclnvalidate invalid); | 

Notifies the container's active view that the server has changed either the contents or the 
appearance of the object. The invalid parameter indicates what needs changing. It can be 
invData, invView, or both combined with the OR operator (| ). If the container is an 
ObjectComponents application, its active view generates an OC. _VIEWFARTIN VALID 
message. 


See also OC_VIEWxxxx messages, TOcInvalidate enum 


IsOpenEditing 
bool IsOpenEditing() const; 
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Returns true if the view is currently engaged in an open editing session. Open editing 
occurs when the user chooses an object's Open verb. Open editing takes place in the 
server's own frame window, unlike in-place editing, which takes place in the container's 
window. Remote view objects are used in both kinds of editing. 


Load 

bool Load(IStorage* storagel); 

Reads from storage! information specific to the remote view. This information is part of 
the data the server stores in the container's file when asked to save an object. Load 
returns true for success. 


[Storage is a pointer to an OLE interface. storagel can be a pointer to a TOcStorage object, 
the ObjectComponents implementation of that interface. 


See also TOcRemView::Save 


Rename | 

virtual void Rename(); 

Updates the name string ObjectComponents generates to distinguish the parts in a 
compound document. TOcRemView calls Rename during construction to find out what 
the container wants to call the object. It is usually not necessary for you to call Rename 
directly. 


Save 

bool Save(IStorage* storagel); 

Writes to storagel information specific to the remote view. This information becomes 
part of the object data stored in the container's compound document file. Returns true 
for success. 


[Storage is a pointer to an OLE interface. storagel can be a pointer to a TOcStorage object, 
the ObjectComponents implementation of that interface. 


See also TOcRemView::Load 


TOcSaveLoad struct ocflocview.h 


Holds information that a view uses when loading and saving its OLE object parts. The 
OC_VIEWLOADPART and OC_VIEWSAVEPART messages carry a ne to this 
structure in their /Params. 


The TOleView processes the load and save messages for you. If you are programming 
with the ObjectWindows Doc/View model, then you do not need to use the 
TOcSaveLoad structure directly. For examples that show how to process the load and 
save messages, look at the source code for the EoViewSavePart and EvViewLoadPart 
methods in TOleView. | 


See also 
OC_VIEWxxxx messages, TOleView::Ev ViewSavePart, TOleView::EvViewLoadPart 
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Public data members 
Release 
bool Release; 


Is true if the view should keep the storage object for ratake file operations and false if it 
should forget the storage object after using it once. 


—- Storagel 


IStorage far* Storagel: 

Points to the storage object assigned to hold the part. ObjectComponents implements 
the standard OLE [Storage interface in TOcStorage, so TOcStorage can be used to 
construct an [Storage. 


TOcScaleFactor class ocflocview.h 


Form 1 


Form 2 


The TOcScaleFactor class carries information from a container to a server about how the 
container wants to scale its document. For example, if the container has a Zoom 
command and the user chooses to magnify the document to 120%, the server should 
match the scaling factor when it draws objects embedded in the container. 


ObjectComponents passes a reference to an TOcScaleFactor object in the [Param of 
OC_VIEWGETSCALE and OC_VIEWSETSCALE messages. When a container receives 
OC_VIEWGETSCALE, it fills in the object with scaling information. When a server 
receives the OC_VIEWSETSCALE information, it reads the scaling values and can use 
them in its paint procedure. 


TOcScaleFactor stores scaling information in its two TSize members, SiteSize and PartSize. 
The names refer to the area where the container wants to draw an object (the site) and 
the object itself (the part.) The values in the members need not be the actual size of the 
site or the part, however. What matters is the ratio of the two sizes. If the SiteSize values 
are twice as large as the PartSize values, then the server is ig asked to draw the object 
at twice its default size. 


If you are programming with ObjectWindows, then the TOleWindow class takes care of 
scaling for you. For examples showing how to handle scaling without the benefit of 
ObjectWindows, look at the source code for the following TOleWindow methods: 
EvViewGetScale, EvViewSetScale, and SetupDC. | 


See also 
OC_VIEWxxxx messages, TOleWindow::EvViewGetScale, 
TOleWindow::EvViewSetScale, TOleWindow::SetupDC, TSize class 


Public constructors 


Constructors 
TOcScaleFactor(); 
Initializes the site and part extents to 1 so the scaling factor is 100%. 


TOcScaleFactor(const RECT& siteRect, const TSize& partSize); 
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Form 3 


Form 1 


Form 2 


TOcScaleFactor class 


Bases the initial scaling factor on the values in the given rectangle structure and size 
object. Calculates the extents of the rectangle siteRect and sets them in SiteSize. Copies 
partSize to PartSize. 


TOcScaleFactor(const BOleScaleFactor far& scaleFactor); 

Bases the initial scaling factor on the values in scaleFactor. BOleScaleFactor is a structure 
that the BOCOLE support library uses internally to carry scaling information. You 
should not have to use the structure directly. 


Usually you do not have to construct a TOcScaleFactor object directly. 
ObjectComponents creates it for you and passes it in the OC_VIEWGETSCALE or 
OC_VIEWSETSCALE message. 


Destructor 
~TOcScaleFactor(); 


Seealso TOcScaleFactor::PartSize, TOcScaleFactor::SiteSize, TSize class 


Public data members 


PartSize 

TSize PartSize; 

Holds two values describing the default horizontal and vertical extent of a server's 
object. The values in PartSize do not need to be actual measurements. What matters is 


the ratio of the values here to the values in SiteSize. That ratio determines how an image 
should be scaled. 


Seealso TOcScaleFactor::SiteSize, TSize class 


SiteSize 

TSize SiteSize; 

Holds two values describing the horizontal and vertical extent of the area a container 
has allotted for displaying a linked or embedded object. The values in SiteSize do not 
need to be actual measurements. What matters is the ratio of the values here to the 
values in PartSize. That ratio determines how an image should be scaled. 


Seealso TOcScaleFactor::PartSize, TSize class 


Public member functions 


operator = 

TOcScaleFactor& operator =(const BOleScaleFactor far& scaleFactor); 

Copies the values in a BOleScaleFactor structure. The BOCOLE support library uses this 
structure internally to carry scaling information. 


TOcScaleFactor& operator =(const TOcScaleFactor& scaleFactor); 
Copies one TOcScaleFactor into another. 


Both forms of the assignment operator copy the values from one scaling object into 
another. 


See also OC_VIEWxxxx messages 
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TOcScrollDir enum 


GetScale 

uint16 GetScale(): 

Retrieves a percentage value expressing the ratio of the part's size to the site's size. For 
example, if the part size is 20 x 20 and the site size is 40 x 40, then GetScale returns 200. 


See also TOcScaleFactor::SetScale 


GetScaleFactor 
void GetScaleFactor(BOleScaleFactor far& scaleFactor) const; 
Fills in scaleFactor with values from the TOcScaleFactor object. BOleScaleFactor is a 
_ structure that the BOCOLE library uses to hold the same scaling information. Usually 
you do not have to call this function directly. _ 


IsZoomed 
bool IsZoomed(); | 
Returns true if the sizes stored for the part and the site do not match. 


SetScale 
void SetScale(uinti6 percent); 
Sets the ratio of the part's size to the site's size. More specifically, SetScale sets the size of 


the part to 100 and the size of the site to percent. 
See also TOcScaleFactor::GetScale 


TOcScrollDir enum . ~ ocffocobject.h 


enum TOcScrollDir 

The OC_VIEWSCROLL event tells the container when the user performs a drag 
movement that should scroll the window. The [Param of the WM_OCEVENT message 
carries one of these values to indicate which direction the window has been asked to 


scroll. 


Pp p 
sdScroliDown — Scroll toward the bottom of the document. 


sdScrollLeft Scroll toward the left edge of the document. 
sdScrollRight Scroll toward the right edge of the document. 


See also — 
EvOcViewScroll event handler, OC_VIEWxxxx messages, TOle View: ‘EvOcViewScroll, 
TOleWindow: EvOcViewScroll, WM_OCEVENT message 


TOcToolbarinfo struct _tlocviewh 


The OC_VIEWSHOWTOOLS message carries a pointer to this structure in its /Param. 
The message asks a server for handles to its tool bars so the container can display them 
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TOcToolbarlinfo struct 


in its own window. This happens during in-place editing when the user opens an object 
in the container in order to modify it. 


The structure has four fields, allowing the server to return handles for up to four tool 
bars. Each tool bar occupies a different edge of the container's client area. 


For examples, look at the source code for TOleWindow::EvOcViewShowTools and 
TOleView::EvOcViewShowTools. The default implementations of these methods allow a 
single tool bar at the top of the client area. To give the container more tool bars, handle 
the OC_VIEWSHOWTOOLS message directly yourself. 


See also | 
TOleView::EvOcViewShow Tools, TOleWindow::EvOcViewShow Tools 


Public data members 


HBottomTB 

HWND HBottomTB; | 

Holds a handle to the tool bar that the server wants to place at the bottom of the 
container's client area. 


HFrame 

HWND HFrame; 

_ If Show is true and the server is being asked to display its tool bar, then HFrame holds a 
handle to the frame window where the tool bar is to appear. If Show is false, then 
HFrame holds a handle to the server's own frame window. 


See also TOcToolbarInfo::Show 


HLeftTB 

HWND HLeftTB; 

Holds a handle to the tool bar that the server wants to place at the left edge of the 
container's client area. 


HRightTB 

HWND HRightTB; 

Holds a handle to the tool bar that the server wants to place at the right edge of the 
container's client area. | 


HTopTB 

HWND HTopTB; 

Holds a handle to the tool bar that the server wants to place at the top of the container's 
client area. 


Show 

bool Show; 

Is true to ask that the server display its tool bar or false to request that the server hide 
the tool bar. 
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TOcVerb class 


TOcVerb class — | ocflocpart.h 


Holds information about a single verb that a server supports for its objects. 


A verb is an action the server can perform with one of its objects. A server that creates 
text objects, for example, might support an Edit verb. A server for sound objects might 
support Edit, Play, and Rewind. 


When the user selects an object in a compound document, the container asks the 
TOcPart object for a list of the verbs it can execute. The container displays the verbs on 
its Edit menu. The command for enumerating verbs is TOcPart::EnumVerbs. 


Whenever the user selects a part, the container modifies its Edit menu by adding an item 
for manipulating the object. If the object is part of a Quattro Pro spreadsheet, for 
example, the container adds the command Notebook Object to its Edit menu. If the user 
selects this command, then the container shows a pop-up menu with the notebook's 
verbs, Edit and Open. 


For an example of how to implement these items on the edit menu, look at the source 
code for TOleWindow::CeEditObject in OLEWINDO.CPP. 


See also | 
TOcPart::EnumVerbs 


Public constructor 


Constructor 
TOcVerb(); 
Creates an empty verb object. 


Public data members 


CanDirty 

bool CanDirty; | 

Is true if executing the verb can modify the object so that it might need to be saved or 
redrawn afterwards. For example, the CanDirty field of an Edit verb is always true, and 
the CanDirty field of a Play verb is usually false. 


TypeName | 

LPCOLESTR TypeName; 

Points to the name of the type of object to which this verb belongs. The container usually 
shows this name in the Object item of its Edit menu. For example, if the user has selected 
an object inserted from the server in Step 15 of the ObjectWindows tutorial, TypeName is 
"Drawing Pad," and the container's Edit menu should have an item saying "Drawing 
Pad." Choosing this item leads to a pop-up menu with all the picture's verbs on it. 


The TypeName string comes from the value the server registered for the menuname key in 
its document registration table. 


See also TOcPart::EnumVerbs, menuname registration key 
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Verbindex 

uint VerbIndex; 

Holds the index number that identifies this verb in the server's list of possible verbs. The 
first verb is always 0 and is considered the default verb. If the user double-clicks the 
object, the container should ask the server to execute its default verb. 


VerbName 
LPCOLESTR VerbName; 
Points to the name of the verb. This is the string that the container adds to its Edit menu. 


TOcView class ocflocview.h 


Base class 

TUnknown 

TOcView manages the presentation of a container's compound document containing 
linked and embedded objects. Each object in the document is represented by an object of 
type TOcPart. The document view knows which parts are selected or activated. It scrolls 
the window and remembers which parts are visible. It transfers parts to and from the 
document through the Clipboard or through drag-and-drop operations. 


Every TOcView has a corresponding TOcDocument. The ObjectComponents document 
object implements the OLE interfaces that manipulate the data in a compound 
document. TOcView implements the interfaces the manipulate the appearance of a 
compound document. 


TOcView is a COM object and implements the [Unknown interface. 


See also 
TOcApp class, TOcDocument class, TOcPart class, TUnknown class 


Public constructor 


Constructor 

TOcView(TOcDocument& doc, TRegList* regList = 0, |Unknown* outer=0); 

doc refers to the TOcDocument object that corresponds to the view. TOcDocument 
manages the data in a compound document, and TOcView manages the appearance of 
the document on the screen. 


regList is the registration structure for a particular document. Use the | 
BEGIN REGISTRATION and END_REGISTRATION macros to create an object of type 
TRegList. 


outer is the root interface of an outer object inside which the new view is asked to 
aggregate itself. 


See also BEGIN REGISTRATION macro, TAutoObject class, TOcDocument class 
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Public member functions 


ActivatePart 

bool ActivatePart(TOcPart* part); 

Attempts to activate the given part (by calling TOcPart::Activate). Returns true if the 
designated part becomes active and false piney wise: If any other part was already 
active, it is deactivated first. 


_ See also TOcPart::Activate, TOcView::ActivePart, TOcView::GetActivePart 


BrowseClipboard 

bool BrowseClipboard(TOclnitInfo& initinfo); 

Displays the Paste Special dialog box showing the available formats for the data 
currently on the Clipboard, allowing the user to choose what format to paste. Returns 
true if the user pastes data and false if the user cancels or the dialog box fails. 


Create initInfo first by passing the view to the TOcInitInfo constructor. BrowseClipboard 
fills initInfo with information about the object. Then use initInfo to create anew TOcPart. 


_ This function calls TOcApp::BrowseClipboard. 


See also TOcApp: :BrowseClipboard, TOcApp::BrowseLinks, TOcInitInfo class, 
TOcPart class 


_ BrowseLinks 
bool BrowseLinks(); _ 
Displays the Links dialog box showing all the linked objects in the compound document 
and what they are linked to. The user can modify the displayed links, perhaps to 
reconnect with a file that was moved. Returns false if an error prevents the dialog box 
_ from being displayed or if the user cancels the dialog box. 


See also TOcApp::BrowseClipboard 


Copy 

bool Copy(TOcPart* part); 
Creates a copy of a linked or embedded object and places it on the Clipboard. Returns 
true if the operation succeeds. Call Copy in response to Cut or Copy commands from the 
Edit menu. 


EvActivate 

void EvActivate(bool activate); 

A container calls this function if any of its windows gains focus while any a its linked or 
embedded objects is being edited in place. EvActivate restores focus to the in-place 
activated view. If the user clicks in the client window of an MDI frame, for example, the 
client window needs to shift the focus back to the view, which in turn restores focus to 
the activated part. A part engaged in in-place editing should always retain the focus. 


activate should be true if the window is gaining focus and false if it is losing it. 


See also TOcView::EvClose, TOcView::EvResize, TOcView::EvSetFocus 


EvClose | 
virtual void EvClose(); 
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TOcView class 


A container calls this function to tell ObjectComponents that the window associated 
with the view has closed. 


See also TOcView::EvActivate, TOcView::EvResize, TOcView::EvSetFocus 


EvResize 

void EvResize(); 

A container calls this function to tell OLE hea the window associated with the view 
changes size. OLE might need this information to let a server modify its tool bar during 
in-place editing. : 

Seealso TOcView::EvActivate, TOcView::EvClose, TOcView::EvSetFocus 


EvSetFocus 

bool EvSetFocus(bool set); 

A container calls this function to tell OLE that the window associated with the view has 
either received or lost the input focus. Make set true if the window gained the focus or 
false if it lost the focus. 


The function returns false if the view is unable to receive the focus. That happens if an 
object in the view is engaged in in-place editing. Such objects retain the focus until the 
editing session ends. 


Seealso TOcView::EvActivate, TOcView::EvResize, TOcView::EvSetFocus 


GetActivePart 

TOcPart* GetActivePart(); 

Returns the currently active part. If the view does not contain an active part, the return 
value is 0. 


Seealso TOcView::ActivePart, TOcView::ActivatePart 


GetOcDocument 

TOcDocument& GetOcDocument(); 

Returns the ObjectComponents document associated with the view. Views and 
documents work in pairs. TOcView manages the appearance of a compound document 
and TOcDocument manages the data in it. 


Seealso TOcDocument class, TOcView::OcDocument 

GetOrigin 

TPoint GetOrigin() const; 

Returns the physical coordinates currently mapped to the upper left corner of the 


container window's client area. ObjectWindows programmers can ignore this method 
because TOleWindow performs scrolling for you. 


Seealso TOcView::Origin, TOcView::ScrollWindow, TPoint class 


GetWindowRect 
TRect GetWindowRect() const; 
Returns the client rectangle for the view window. 


Seealso TOcView::GetOrigin, TRect class 
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TOcView class 


InvalidatePart 

void InvalidatePart(const TOcPart* a 

Sends an OC_VIEWPARTINVALID message to the container indo If the container 
window responds with false to indicate it has not processed the message, InvalidatePart 
tells the system that the area inside the part's ene rectangle is invalid and needs 
repainting. | 


Paste 

bool Paste(bool linking = false); 

Inserts an object from the Clipboard into the compound document. If linking is true, 
Paste will try to create a link rather than ne the new object. Make si true 
when processing the Paste Link command. 


RegisterClipFormats 

bool RegisterClipFormats(TRegList& regList); 

Tells OLE what Clipboard formats the document understands. The list of formats comes 
from regList, the document's registration structure. Use the BEGIN_REGISTRATION 
and END_REGISTRATION macros to create regList. Also, the REGFORMAT macro 
places Clipboard format entries in the structure. To hee custom Clipboard formats, 
be sure to call TOcApp::AddUserFormatName as well. 


RegisterClipFormats is called automatically when the view is constructed. 


See also BEGIN REGISTRATION macro, REGFORMAT macro, 
TOcApp::AddUserFormatName, TOcView::FormatList 


ReleaseObject 

virtual void ReleaseObject(); 

Call this instead of delete to destroy a TOcView object when you are through with it. 
ReleaseObject decrements the view's internal reference count and dissociates the view 
from its window. 


Seealso TOcView::SetupWindow 


Rename 

virtual void Rename(); 

Tells OLE when the name assigned to a compound document has changed. OLE 
updates its internal records. Also, the associated TOcDocument object passes the new 
name to any linked or embedded objects it contains. 


scrollWindow 

void ScrollWindow(int dx, int dy); 

Brings new areas of a document into view by adjusting the origin of the container 
window. dx and dy are horizontal and vertical offsets added to the origin. This function 
is usually called in response to messages from the window scroll bars or from the arrow | 
keys. 

Seealso TOcView::GetOrigin, TOcView::Origin 


SetLink 
void SetLink(bool pasteLink); 
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Form 1 


Form 2 


TOcView class 


Sets an internal flag that determines whether Paste operations create linked or 
embedded objects. More specifically, SetLink alters the priority of the document's 
registered Clipboard formats. You set the original priorities with the first parameter of 
the REGFORMAT macro. If pasteLink is true, then SetLink moves the Link Source format 
to the top of the list. If pasteLink is false, it restores the Link Source format to its original 
position behind Embed Source. 


It is usually not necessary to call SetLink directly because the Paste method calls it for 
you. 


See also REGFORMAT macro, TOcView::Paste 


SetupWindow 

void SetupWindow(HWND hWin); | 

Tells the view what window is associated with it. The view sometimes sends 
notification messages to its window. Usually this function should be called from the 
SetupWindow member of the container's window class. TOleWindow performs this task 
automatically. 


See also OC_VIEWxxxx messages, TOleWindow::SetupWindow, TOcView::Win 


Protected destructor 


Protected Destructor 
~TOcView(); 
Destroys the view object. 


Protected member functions 


ForwardEvent 
uint32 ForwardEvent(int eventid, const void far* param); 


uint32 ForwardEvent(int eventld, uint32 param = 0); 


Both forms send a WM_OCEVENT message to the container's window. The eventld 
parameter becomes the message's wParam and should be one of the OC_APPxxxx or 
OC_VIEWxxxx constants. The second parameter becomes the message's [Param and 
may be either a pointer (Form 1) or an integer (Form 2). Which form you use depends on 
the information a particular event needs to send in its /Param. 


"See also OC_APPxxxx messages, OC_VIEWxxxx messages, TOcView::Win, 


WM_OCEVENT message 


Init 

void Init(TRegList* regList); 

Initializes a newly created view object. Init is called by both of the TOcView constructors. 
Usually you don't need to call it directly yourself. TRegList is the data type that holds all 
the registry keys and associated values for a single registration table. regList must be a 
document registration table (the structure created by the registration macros and 
conventionally named Dockeg). 
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Init makes this view the document's active view, connects with the BOCOLE support 
library, and registers eer Clipboard formats. 


Shutdown 

void Shutdown(); 

Called by the destructor of derived aacees to ecibaee helper objects that the view holds 
internally. , | 


Seealso TOcView public constructors and destructor 


- Protected data members 


ActivePart | 

TOcPart* GetActivePart();. | 

Returns the currently active part. If the view does not contain an active part, the return 
value is 0. 


Seealso TOcView::ActivePart, TOcView::ActivatePart 


Extent 

TSize Extent; | 

Holds the current width and height of the container window's client area. Both are 
measured in device units. 


See also TOcView::GetWindowRect 


FormatList 

TOcFormatList FormatList; 

Holds information about all the Clipboard formats the compound document supports. 
The list is generated from information the application registers for the types of 
documents it supports. 


Seealso TOcFormatList class, TOcView::RegisterClipFormats 


Link 
int Link; 
Used internally by the Paste method to adjust the priority of link source format. 


OcApp 
TOcApp& OcApp; 
A view stores the pe eauen that owns it in this protected data member. 


OcDocument 

TOcDocument& OcDocument; 

A view stores the document object that owns the view in this protected data member. 

The view object manages the appearance of a compound document, and the document 
_ object manages the data. 


See Also TOcView::GetOcDocument 
Origin | 
TPoint Origin; 
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Holds the coordinates of the point currently mapped to the upper left corner of the 
container window's client area. 


See Also TOcView::GetOrigin 
Win 
HWND Win; 


Holds a handle to the window where the view draws itself. The ForwardEvent method 
sends messages to this window. 


See Also TOcView::ForwardEvent, TOcView::SetupWindow 


WinTitle 

string WinTitle; 

Holds the original caption string of the container's window. The caption is usually 
modified as the user moves from part to part within the document. When no part is 
active, the view restores the window's title to this original string. 


The OC_VIEWPAINT message carries a pointer to this structure in its /Param. The 
message notifies a server that it should update its painting of an object. The structure 
carries information about the area that needs repainting. Generally a program should 
respond by calling paint methods on the window or view that receives the message. For 
examples, look at the source code for TOleWindow::EvOcViewPaint and 
TOleView::EvOcViewPaint. 


See also / 
OC_VIEWxxxx messages, TOleView::EvOcViewPaint, TOleWindow::EvOcViewPaint 


Public data members 


Aspect 

TOcAspect Aspect; 

Holds an enumerated value that tells how the part is to be drawn. A single object can 
often be drawn in more than one way. For example, the server might show the object's 
full contents, a miniature representation of the contents, or an icon that represents the 
type of object without indicating its specific contents. 


Seealso TOcAspect enum 
Clip 
TRect* Clip; 


Designates the area where the part should be allowed to draw. The server can clip the 
output to this area to avoid drawing outside its allotted space. 


Seealso TRect class 


DC 
HDC DC; 
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Contains a handle to the device context where the repainting should occur. 


Part | 

TOcPart* Part; | “23 

Points to the part that needs to be redrawn. This member can be used to ask the part to 
repaint itself. In the current implementation of ObjectComponents, this member is not 
used. 


See also TOcPart class 


Pos 

TRect* Pos; os , | 

Specifies the upper left corner of the server object that has become invalid and needs 
repainting. 


See also TRect class 


TOleAllocator class ocfloleutil.h 


A linking and embedding .EXE application creates a memory allocator object in order to 
tell OLE what memory manager the system should use when allocating and 
deallocating memory on behalf of the server. Unless you have particular memory 
management needs, it's easiest to let OLE use its default allocator. 


When writing a linking and embedding application, you usually do not need to create a 
memory allocator object directly because your registrar object takes care of it for you. 
The only applications that create memory allocators directly are automation servers that 
do not support linking and embedding. Because automation servers don't create — 
TOcApp objects, they do need to create TOleAllocators. 


DLL servers do not need a memory allocator because the system uses whatever 
allocator the .EXE client designates. 


See also 
TOcRegistrar class, TRegistrar class 


Public constructors and destructor 


Constructor 
Form1 TOleAllocator(IMalloc* mem = 0); 
Initializes the OLE system library and, if mem is nonzero, registers a custom memory 
allocator. Unless you have particular memory management needs, it is easiest to let OLE 
use its default allocator. To implement your own allocator, refer to the OLE 
documentation on the [Malloc interface. 


Form2  TOleAllocator(); : 
Tells OLE to use the custom memory allocator. Does not initialize the OLE system 
library. In .EXE applications, the registrar object initializes the OLE library. In DLL 
servers, the .EXE client provides the allocator. 
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Destructor 

~TOleAllocator(); 

Releases the memory allocator (either the default allocator or a custom allocator) and 
uninitializes the OLE system. 


Seealso TOcRegistrar Class, TRegistrar Class 


Public member functions 


Alloc 

void far* Alloc(unsigned long size); 

Calls the Alloc method on the active memory allocator to request a block of memory. size 
gives the size of the block. Unless you have registered a custom memory allocator, Alloc 
calls OLE's default allocator. If the request fails, Alloc returns 0. 


See Also TOleAllocator::Free_ 


Free 

void Free(void far* block); 

Calls the Free method on the active memory allocator to release a block of memory 
previously allocated with Alloc. block points to the base of the area to be released. Unless 
you have registered a custom memory allocator, Free calls OLE's default allocator. 


Seealso TOleAllocator::Alloc_ 


Public data member 


Mem 

[Malloc* Mem; 

Points to the active memory allocator object. Unless you have registered a custom 
memory allocator, Mem points to OLE's default allocator. 


TRegistrar class ocflocreg.h 


T Registrar manages all the registration tasks for an application. It processes OLE-related 
switches on the command line and records any necessary information about the 
application in the system registration database. If the application is already registered in 
the database, the registrar confirms that the registered path, progid, and clsid are still 
accurate. If not, it reregisters the application. 


Every ObjectComponents application needs to create a registrar object. If your 
application supports automation but not linking and embedding, then create a 
TRegistrar object. To support linking and embedding—alone or along with 
automation—then create a TOcRegistrar instead. TOcRegistrar extends TRegistrar by 
connecting the application to the BOCOLE support library interfaces that support 
linking and embedding. 


An application's main procedure — performs these actions with its registrar: 
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TRegistrar class 


¢ Construct the registrar, passing it a pointer to the application's factory callback. 


¢ Call IsOptionSet to check for options that might affect how the application chooses to — 
start (for example, remaining invisible if invoked forembedding. __ 


e Call Run to enter the program's message loop. 


See also 
TOcRegistrar class 


Public constructor and destructor 


Constructor | 

TRegistrar(TRegList& reginfo, TComponentFactory callback, string& cmdLine, HINSTANCE hinst); 

regInfo is the application registration structure (conventionally named appReg). callback is 
the factory callback function that ObjectComponents invokes when it is time for the 
application to create a document. An ObjectWindows program can use the TOleFactory 
class to create this callback. cmdLine points to the command line received when the 
application was invoked. hInst is the application instance. | 


Destructor 
virtual ~TRegistrar(); 
Deletes objects the registrar maintains internally. 


The constructor processes OLE-related switches and removes them from the command 
line. (Call IsOptionSet to determine what switches were found.) It also initializes some 
settings from the application registration table. If the application is a DLL, the 
constructor initializes the global Dll Registrar variable. | 


See also string class, T[ComponentFactory typedef, TOleFactory class, 
TRegistrar::IsOptionSet 


Public member functions 


CanUnload 

virtual bool CanUnload(); 

Returns true if the application i is not currently serving any OLE clients and false 
otherwise. 


CreateAutoApp 

TUnknown* CreateAutoApp(TObjectDescriptor app, uint32 options, |Unknown* outer = 0); 

Creates an instance of an automated application. This method is usually called from the 
application's TComponentFactory callback function. 


app is the automation server's primary automated class created from the 
TAutoObjectDelete<> template. 


options contains the application's mode.flags. This is usually the same value passed in to 
the factory callback function. The possible values are enumerated in TOcAppMode. 
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outer points to the [Unknown interface of an outer component under which the 
application is asked to aggregate. 


_ The return value points to the new OLE application object. 


Seealso TAutoObjectDelete<> class, TComponentFactory typedef, 
TRegistrar::CreateAutoObject 


CreateAutoObject 
Form 1 TUnknown* CreateAutoObject(TObjectDescriptor obj, TServedObject& app); 
app is the automated OLE application object. 


obj is the automated C++ object. 


Form2 TUnknown* CreateAutoObject(const void* obj, const typeinfo& objlnfo, const void* app, const typeinfo& applnfo); 
app and obj are the same as in Form 1. 


objInfo identifies the type of object in obj. appInfo identifies the type of object in app. Both 
values can be obtained using typeid. 


CreateAutoObject asks an automated application to instantiate one of its automated 
objects. It is usually called from the application's TComponentFactory callback function. 
Which form you call depends on what information you have to identify the kind of 
object you want to create. 


See also T?ComponentFactory typedef, TRegistrar::CreateAutoApp, typeid, typeinfo 
class 


GetFactory 

virtual void far* GetFactory(const GUID& clsid, const GUID far& iid); 

Returns a pointer to the factory interface for creating type object indicated by clsid. tid 
names the particular interface you want to receive. If the registrar is unable to find an iid 
interface for clsid objects, it returns zero. 


ObjectComponents calls a DLL's GetFactory member every time a new client loads the 
DLL. Usually you do not need to call GetFactory yourself. 


GetOptions 

uint32 GetOptions() const; | 

Returns a 32-bit integer containing bit flags that reflect the application's running mode. 
Some of the flags are set in response to command-line switches. Others are set directly 
by ObjectComponents. For a list of the mode flags, see the TOcAppMode enum. 


Seealso TOcAppMode enum, TRegistrar::IsOptionSet, TRegistrar::ProcessCmdLine, 
TRegistrar::SetOption 


IsOptionSet 

bool IsOptionSet(uint32 option) const; 

Returns true if a particular option was set as a flag on the application's command line, 
and false if the option was not set. The flags are set by the ProcessCmdLine method. 


For a list of possible values option can assume, see the TOcAppMode enum. 


Seealso TOcApp::IsOptionSet, TOcAppMode enum, TRegistrar::GetOptions, 
TRegistrar::ProcessCmdLine, TRegistrar::SetOption 
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ProcessCmdLine 

void ProcessCmdLine(string& cmdLine); 

Locates any OLE-related switches on the application’ s command line (or passed in toa 
DLL server from ObjectComponents). The switches tell the program whether it has been 
launched independently or as a server, whether it should register or unregister itself, 
whether to create a type library, and signal other running conditions as well. 
ProcessCmdLine records the presence of each flag it finds. You can call pO onoget to 
determine the results. : 


The command line is always processed for you when the registrar object is constructed. 
Usually you do not need to call this function directly. 


cmdLine contains the string of arguments passed to the program on its command line. 
ProcessCmdLine removes OLE-related switches from the command line. That lets you 
process cmdLine afterwards for any of your own arguments without worrying about 
OLE arguments. 


Seealso string class, TRegistrar::IsOptionSet 


ReleaseAutoApp 

void ReleaseAutoApp(TObjectDescriptor app); 

This method is used by an application's factory callback function if the application must 
detach itself from OLE before it can shut down. Detaching the application is necessary 
when an automated application has registered its application object for its class, 
allowing the controller to manipulate it. 


RegisterAppClass 

void RegisterAppClass(); 

Tells OLE that an automated application is up and ready to create an application 
instance. Has no effect if called from an application that does not support automation. 


For convenience, it is recommended that every ObjectComponents application, even 
those that do not support automation, call RegisterAppClass on starting up and 
UnregisterAppClass when closing down. This habit is harmless even if sometimes 
unnecessary and ensures that you will not forget to include registration functions if you 
later add automation. 


Seealso T’Registrar::UnregisterAppClass 


Run 

virtual int Run(); 

Call this function to execute your program. If the application was built as an .EXE file, 
then Run lets the application enter its message loop. If the application was built as a 
DLL, then Run returns without entering the message loop. DLL servers must wait for 
OLE to call their factory before they run. The purpose of the Run function is to let you 
build your applications as either an .EXE or a DLL without having to ae your code. 


In .EXE programs, Run performs the following steps: 
e Ifthe application is automated, call RegisterAppClass. 


e Call the factory function to run the application. The application enters its message 
loop. 
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¢ Call the factory function to shut down the application. 
e Ensure that the application's TOcApp connector object is properly released. 
Seealso TOcApp, TRegistrar::RegisterApp, TRegistrar::Shutdown 


SetOption 

void SetOption(uint32 bit, bool state); 

Modifies the application's running mode flags. bit contains bit flags from the 
TOcAppMode enum. If state is true, SetOption turns the flags on. If state is false, it turns 
the flags off. You should never have to call this function because ObjectComponents 
always maintains the mode flags. 


Seealso TOcAppMode enum, TRegistrar::GetOptions, TRegistrar::IsOptionSet, 
TRegistrar::ProcessCmdLine 


Shutdown 

virtual void Shutdown(IUnknown* releasedObj, uint32 options); 

Calls the application's factory function and asks it to make the application stop. Ensures 
that the application's TOcApp connector object is properly released. In the normal path 
of execution, the Run command performs the same tasks. Call Shutdown to terminate the 
application directly. 


Seealso TOcApp, TRegistrar::Run 


UnregisterAppClass 
void UnregisterAppClass(); 
Announces that the application is no longer available for OLE interactions. 


Seealso TRegistrar::RegisterAppClass 


Protected data member 


AppDesc 

TAppDescriptor& AppDesc; 

Holds the application descriptor. ObjectComponents uses an application descriptor 
internally to manage information about a component. (Like EXEs, each DLL gets an 
application descriptor of its own.) TAppDescriptor is undocumented because it is used 
only internally and is subject to change. The registrar classes, TOcRegistrar and 

T Registrar, are the supported interfaces to the application descriptor. The registrar 
constructs the descriptor, and most of its member functions call descriptor functions to 
perform the work. 


Usually you will not need to manipulate this data member directly. 


Protected constructor 


Constructor 
TRegistrar(TAppDescriptor& appDesc); 
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The protected constructor is used jie by the derived class TOcRegistrar. TApp Descriptor 
is a class that both registrar objects (TRegistrar and TOcRegistrar) use nitemay; to hold — 
information about an application. | 


_TUnknown class a octloleutil.h 


Implements the standard OLE [Unknown interface. ObjectComponents derives some of 
its own classes from TUnknown, so usually you do not need to use it directly yourself. 
Advanced users, however, might find TUnknown helpful in creating their own custom 
Component Object Model (COM) objects. 


The TUnknown class is the basis for the ObjectComponents implementation of object 
aggregation. With aggregation, you can make distinct components work together as a 
single OLE object. A single primary object becomes the outer object, and secondary 
objects behave as though they are parts of the primary object. For this to work, 
whenever any inner object is asked for its [Unknown interface, it must return the 
IUnknown that belongs to the outer object. If the outer object is asked for an interface it 
does not support, it forwards the request to the chain of attached inner objects. All the 
interfaces supported by any object in the aggregation are available through the | 
QueryInterface method of the outer object. 


Aggregation is established in the TComponentFactory callback function. Each component 
receives the [Unknown pointer to its outer object and returns its own [Unknown pointer 
to be placed in the chain of secondary objects. 


see also 
TComponentFactory typedef 


Public member functions 


Aggregate 

[Unknown& Aggregate(TUnknowné inner); 

Aggregates a new object under the current object. inner points to the [Unknown interface 
of the new object. The current object stores inner for use in responding to future 
QuerylInterface calls. It also calls AddRef on the inner pointer. 


If this is already part of an aggregation, inner is passed down to the last inner object in 
the chain. 


Aggregate returns a reference to the object's own outer [Unknown interface. The newly _ 
added object should use the return value as its Outer pointer, too. To aggregate this 
under an object that is not a TUnknown, call SetOuter instead. 


See also TUnknown::SetOuter, TUnknown::Outer 
GetOuter | 
[Unknown* GetOuter(); 


Returns a pointer to the object's outer I Unknown interface, the one that belongs to the 
primary object in a group of aggregated objects. 
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See also TUnknown::SetOuter, TUnknown::Outer 


GetRefCount 

unsigned long GetRefCount(); 

Returns the reference count of the outer object. If this is not aggregated, then 
GetRefCount returns the object's own reference count. 


The reference count tells how many clients hold pointers to the object. The destructor 
prevents the object from being destroyed if the reference count is not 0. 


operator [Unknown&() 

operator [Unknown&(); 

Returns a reference to the object's outer [Unknown interface. Does not increment the 
object's reference count. | 


operator [Unknown*() 

operator [Unknown*(); 

Returns a pointer to the object's outer [Unknown interface. Increments the object's 
reference count first. 


See also TUnknown::operator [Unknown&() 


SetOuter 

[Unknown* SetOuter(IUnknown* outer); 

Tells the object to aggregate itself under the object outer. When asked for its [Unknown 
interface, this always returns outer. SetOuter returns the object's own [Unknown interface 
to the outer object. It does not call AddRef before returning the pointer. 


If outer is 0, SetOuter ignores outer but still returns its own [Unknown interface. 


SetOuter is called to make the object aggregate under an unknown outer object. If the 
outer object is also a TUnknown, call Aggregate instead. Aggregate sets the object's 
inner pointer as well as its outer pointer. 


See also TUnknown::Agegregate, TUnknown::GetOuter, TUnknown::Outer, 
TUnknown::operator IUnknown*() 


Protected constructor and destructor 


Constructor 

TUnknown(); 

Creates a TUnknown object with an initial reference count of 0. Initially the object is not 
aggregated with any other object. 


These members are protected because only a derived class should be able to construct a 
TUnknown object. TUnknown is meant to be a base for other objects, not an independent 
object. 


Destructor 
virtual ~TUnknown(); 
_ Deletes the object. 


See also 9TUnknown::Aggregate 
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Protected member functions | 


QueryObject 

virtual HRESULT QueryObject(const GUID far& iid, void far* far* pif); 

Asks whether the object supports the interface identified by iid. If the object supports the 
interface, the function returns HR_NOERROR and places a pointer to the interface in pif 


The implementation of QueryObject in TUnknown always fails. It always returns 
HR _NOINTERFACE. Classes derived from TUnknown should override this function. 


For examples of override functions, look at the source code for classes such as TOcApp 
and TOcView. 


ThisUnknown 

[Unknown& ThisUnknown(); 3 

Returns a reference to the [Unknown interface for this, not to the outer or inner 
ageregated objects. 


Protected data member 


Outer 

|[Unknown* Outer; 

Holds a pointer to the [Unknown interface of the outer object in a group of aggregated 
objects. 


Seealso TUnknown::GetOuter, TUnknown::SetOuter 


Base class 

TXBase 

TX Auto is the exception object that ObjectComponents throws when it encounters an — 
unexpected error while processing automation calls. The possible errors are indicated 
by the TError nested enum values. 


see also 
TXBase class (OWL.HLP), TXObjComp class, TXOle class, TXRegistry class 


Public constructor 


Constructor 
TXAuto(TXAuto::TError err); 
Constructs an exception object to describe the problem indicated by err. 


_ Seealso TXAuto::TError enum 
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Public data member 


ErrorCode 
TError ErrorCode; 
Holds the code that identifies the problem this object was constructed to describe. 


Seealso TXAuto::TError enum 


Type definition 


TError 

enum TError 

The values of the enumeration identify possible errors that can occur during 
automation. 


XNoError No error occurred. 
xConversionFailure Problem converting a value from a VARIANT union to the expected data type. 


xNotIDispatch Attempted to send an automation command to an object that does not execute 
commands. 


xForeignIDispatch Attempted to send an automation command to an automated object that does not 


derive from TAutoProxy. 
xTypeMismatch A supplied argument cannot be converted to the required type. 
xXNoArgSymbol A command attempted to use more arguments than the server recognizes. 
xParameterMissing as automation call failed to provide a required argument when setting a property 
value. 


xNoDefaultValue A parameter is missing and no default value was supplied. 


xValidateFailure The code in a user-defined validation hook indicated that the argument values it 
received are unacceptable. 


Base class 
TXBase 


TXObjComp is the exception object that ObjectComponents throws when it encounters 
an unexpected error while processing its own internal code. The possible errors are 
indicated by the TError nested enum values. 


See also 
TXAuto class, TXBase class, TXOle class, TXRegistry class 


Public constructor 


Constructor 
TXObjComp(TXObjComp::TError err, const char* msg = 0); 
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Constructs an exception object to describe the problem indicated by err. Associates the 
optional msg string with the error. 


Seealso T’XObjComp::TError 
Public member function 
ErrorCode 


TError ErrorCode; 
Holds the error code that identifies the problem this robles was constructed to describe. 


See also T’XObjComp::TError enum 


Type definition 


TError 

enum TError 

The values of the enumeration denne possible errors that can occur inside 
ObjectComponents. 


Application Errors 

XNoError No error occurred. 7 

xBOleLoadFail The BOCOLE support library could not be loaded. 

xBOleBindFail ObjectComponents could not get a ey interface from the BOCOLE 
support library. 

_ xDocFactoryFail | TOcApp was unable to register or unregister the application with OLE. 
xRegWriteFail The registrar could not write to the system registration database. 
Document and Part Errors 
xMissingRootIStorage The document where a part was asked to construct itself does not possess a 

root storage object. (Without a storage, the document has nowhere to store 
its parts.) 
xInternalPartError ObjectComponents was unable to create a part object. 
xPartinitError | ObjectComponents was unable to initialize a newly created part. 
xDocSaveError A TOcDocument could not write itself to a file. 
Storage Errors 
xStorageOpenError A document was unable to open its storage object. 
xStreamOpenError A document was unable to open the stream object it needs for file I/O. 
xStreamWriteError A document was unable to write to the stream object it needs for file 1/O. 
TXOle class — ocffoleutil.h 
Base class 
TXBase 


TXOle is the exception object that ObjectComponents throws when it encounters an 
ee error while executing an OLE API call. 
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Form 1 


Form 2 


Form 1 


Form 2 


TXOle class 


The object's Check method is static so that you can call it without actually creating a 
TXOle object. If the parameters you pass indicate an error has occurred, Check creates a 
TXOle object and throws the exception for you. 


See also 
TXAuto class, TXObjComp class, TXRegistry class 


Public constructors and destructor 


Constructors 

TXOle(const char far* msg, HRESULT stat); 

Creates an OLE exception object. msg points to an error message and stat holds the 
return value from an OLE API call. 


TXOle(const TXOle& copy): 
Constructs a new OLE exception object by copying the one passed as copy. 


Usually you do not need to construct an OLE exception object directly. Call Check 
instead. 


Destructor 
~TXOle(); 
Destroys the TXOle object. 


Seealso TXOle::Check 
Public member functions 
Check 


static void Check(HRESULT stat, const char far* msg); 
If stat indicates an error, Form 1 throws a TXOle exception containing the msg error 


string. 


static void Check(HRESULLT stat); 

If stat indicates an error, Form 2 throws a TXOle exception containing the error string 
“OLE call FAILED, ErrorCode = stat" where stat is shown as an eight-digit hexadecimal 
value. 


If you see this error message when running programs, you can look it up in the 
OLE_ERRS.TXT file, which for convenience matches the error codes to corresponding 
comments from the OLE system header files. 


Checks whether an error has occurred and if so throws an exception. stat is the value 
returned by an OLE API call. Check is static so that you can call it without actually 
creating a TXOle object first. If stat indicates an error, then Check creates a TXOle object 
and throws an exception. 
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Public data member 


Stat 
long Stat; 
Stat ("status") holds the result code returned from an OLE API. 


TXRegistry class = |= = —  ____ cetfocdets.h 


Form 1 


Form 2 


Base class 

TXBase 

TXRegistry is the exception object that ObjectComponents throws when it encounters an. 
unexpected error while reading from or writing to the system registration database. 


The object's Check method is static so that you can call it without actually creating a 
TXRegistry object. If the parameters you pass indicate an error has occurred, Check 
creates a TX Registry object and throws the exception for you. | 


See also 


TXAuto class, TXObjComp class, TXOle class 


Public constructors 


Constructors 

TXRegistry(const char* msg, const char* key); 

Creates a registry exception object. msg points to an error message and key points to the 
name of the registry key that ObjectComponents was processing when the exception 
occurred. 


TXRegistry(const TXRegistry& copy); 
The copy constructor constructs a new registry es object by copying the one 
passed as copy. 


Usually you do not need to construct a registry exception directly. Call Check instead. 
Seealso T’XRegistry::Check 


Public member functions 


Check 

static void Check(long stat, const char* key); 

Tests the value of stat to determine if an error has occurred and if so throws an 
exception. stat is the return value from a registration command. key is the name of the 
key that the registration command was processing. 


Check is static so that you can call it without actually creating a TXRegistry object first. If 
stat is nonzero, then Check creates a TXRegistry object and throws an exception. The 
exception carries the message string "Registry failure on key: key, ErrorCode = stat." 
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Key 

const char* Key; 

Points to the name of the registration key that ObjectComponents was processing when 
the exception occurred. 


typehelp registration key 


Registers the name of a Help file (HLP) containing information about the methods and 
properties your program exposes for automation. If the file is not in the same directory 
as the executable, be sure to register helpdir as well. 


typehelp is valid in the application registration table of an automation server. It is 
optional. Also, the file name can be localized, making it easy to have different Help files 
for different languages. 


To register typehelp, use the REGDATA macro, passing typehelp as the first parameter 
and file name as the second parameter. 


See also 
helpdir registration key, REGDATA macro, typelib registration key 


usage registration key 


Determines whether a single instance of your application is allowed to support multiple 
users or whether a new instance should be launched for each new OLE client. The 
—Automation command-line switch overrides this setting and forces single use when an 
automation server is invoked. 


The usage key is valid in any server registration table. It is always optional. If you omit it, 
ObjectComponents by default registers the application to support only one client per 
instance. 


To register the usage key, use the REGDATA macro, passing usage as the first parameter 
and one of the ocrxxxx Usage constants as the second parameter. 


REGDATA(usage, ocrSingleUse) // one client per instance (default) 


See also 
OCrxxxx usage constants, REGDATA macro 


verbn registration keys 


A string naming an action the server can perform with its objects. Containers add the 
active object’s verbs to their Edit menus. 


verb0 is the name of the primary (default) verb for the class. The primary verb is" 
executed if the user double-clicks the object. Use verb1 through verb7 to register 
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additional verbs. The ocrVerbLimit constant, defined in ocf/ocreg.h, represents the 
maximum. number of verbs allowed (8). 


The verbn keys are valid in the document registration tables of a server that supports 
linking and embedding. Every server should register a default verb. Other verbs are 
optional. 


To register a verb, use the REGDATA macro, pases verbn as the first parameter and a 
menu item string as the second parameter. 


REGDATA(verb0, "&Edit") // default action 
REGDATA(verbl, "&Open") // another possible action (optional) 


See also 
REGDATA macro, verbnopt registration keys 


verbnopt registration keys 


| Registers option flags describing the server's verbs. The flags determine how the verbs 
appear on the container's menu. They can be grayed or disabled, for example. 


Verb options are valid in the document registration table of any server that supports 
linking and embedding. They are always optional. Verb options are meaningless unless _ 
you also register verbs. 


To register verb options, use the REGVERBOPT macro, passing a verb key (such as 
verb0 or verb1) as the first parameter. For the second parameter, use ocrxxxx verb menu 
constants. For the third parameter, use ocrxxxx verb attribute constants. 


REGVERBOPT (verb2, ocrGrayed, ocrOnContainerMenu | ocrNeverDirties) 


See also 
ocrxxxx verb menu constants, ocrxxxx verb attribute constants, REGVERBOPT macro, 
verbn registration keys 


version registration key 


Registers a version string for the application and type library. The string can include 
minor version numbers delimited by periods. OLE ignores version numbers after the 
first two (the major and minor version numbers). 


The version key is valid in any registration table. It is always optional. 


To register version, use the REGDATA macro, passing version as the first parameter and © 
a version number string as the second parameter. 


REGDATA(version, "1.0.5") 


See also 
description registration key, permid registration key, permname registration key 
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WM _OCEVENT message 


WM_OCEVENTmessage = _tlocapp 


ObjectComponents defines the WM_OCEVENT message in order to notify an 
application's window when significant OLE-related events occur. 


WM_OCEVENT _ Notification of an OLE event from ObjectComponents. The wParam value identifies 
the particular event. 
See also 


OC_APPxxxx messages, OC_VIEWxxxx messages 
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Overview of ObjectSupport 


This chapter provides an overview of the ObjectSupport classes, libraries, and header 
files, which provide various services that help you design your ObjectWindows 
application. These classes include the following groups: 


e Mathematical classes such as TPoint, TSize, and TRect that define screen coordinates 
and properties of rectangles. 


e Document template classes that make it easier to design Doc/View applications. 


e TLocaleString, which localizes OLE registration information required for containers 
and servers. 


The geometric classes support various operations that you might want to perform on. 
points and rectangles. TPoint encapsulates a two-dimensional point that represents a 
screen position. You can use TPoint to compare, assign, and manipulate points. TSize 
encapsulates a two-dimensional quantity that represents the displacement of an area or 
the height and width of a rectangle. You can use TSize to compare, assign, and 
manipulate sizes. TRect encapsulates the properties of rectangles with sides parallel to 
the x- and y-axes. You can use TRect to perform a variety of rectangle tests and 
manipulations, such as inflating, normalizing, and changing the offset dimensions of a 
rectangle. A parameterized class, [Pointer holds a pointer to its parameterized type. You 
can assign a pointer to a TPointer object and easily remove the object by assigning 0 to 
the pointer. 


Other ObjectSupport classes such as TDropInfo and TDocTemplate provide functions that 
let you manipulate files and documents. TDropInfo, which supports file drag and drop 
operations, makes it easy to determine the number of files dropped, the names of the 
files, and where they were dropped. The templetized classes, TDocTemplate and 
TDocTemplateT, support creating documents and views. You can use these classes to 
create a document template with a specified file description, file filter pattern, and 
default file extension. 


The ObjectSupport library also includes classes and macros designed to simplify the 
process of localizing strings and building registration tables. The localization class, 
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TLocaleString, provides support for ObjectWindows’ Doc/View as well as 
ObjectComponents’ OLE-enabled applications. A struct defining a localizable substitute 
for char* strings, TLocaleString contains functions that translate and compare strings in a 
given language. ObjectWindows’ registration macros simplify the process of building a 
registration table for either an automation server or a non-automated application or 
document. | 


The ObjectSupport library contains one exception class, TXBase, which is the base class 

for both ObjectWindows’ and ObjectComponents’ exception-handling classes. 

Exception classes derived from TXBase are designed to handle specific error conditions, 

such as an out-of-memory error or an attempt to create an invalid window. To handle 

an exception, you will want to derive a class from any one of the ObjectWindows’ 
classes that describe this particular exception. 


The following table lists the files included in the ObjectSupport Library (..\OSL 
directory). 


Table 7.1. | Summary of the ObjectSupport library files 


TRect, TSize, TResId, TDropInfo, TProcInstance, and TPointer. 


doctplL.h Contains definitions of files TDocTemplate, and 
TDocTemplateT<D,V>. 

defs.h Contains common definitions, includes windows.h definitions, 
and deals with BOOL data types. 

except.h Defines class TXBase, the base exception-handling class for 


ObjectWindows and ObjectComponents classes. 
locale.h Defines TLocaleString class as well as registration macros. 
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ObjectSupport library reference 


Registration macros 


The following macros, defined in locale.h, take care of performing various OLE-related 
registration procedures. These macros simplify the process of building a registration 
table (a specific kind of lookup table) for an automation server and for a non-automated 
application or document associated with either a container or a server. A collection of 
vital statistics about an object, the registration table provides an external description 
associated with an object. Some of the information goes into the system registry and is 
used by OLE. Some of the information is displayed in the File |Open dialog box when 
the user selects the Insert Object selection. 


The registration macros build a TRegList structure containing entries of type TRegltem, a 
struct which is defined as follows: 


struct TRegItem { 
char* Key; //Item name 
TLocaleString Value; //String value for the item 
bj | 
Using these macros saves you the trouble of having to build the TRegItem and TRegList 
structures directly. 


Although both servers and containers use the same macros, they pass different kinds of 
information to the registration structures. Depending on the amount of information you 
want associated with your application and whether you want to set up a structure with 
document or application information, use one or more of these registration macros. 
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- BEGIN_ REGISTRATION macro 


Registration macros 


BEGIN_REGISTRATION Begins a registration macro table. 

END_REGISTRATION _ Ends a registration macro table. 

REGDATA | Registers information about the application, for example, class 
ID, description, document filter, and debugger. 

REGDOCFLAG Registers a series of document flags. Required for a document 
registration table. 

REGFORMAT Registers a data format. 

REGICON Registers an icon. 

REGITEM | Registers a customized format. 

REGSTATUS | _ Registers an aspect status. 

REGVERBOPT : Registers an option for a verb. 


REGISTRATION_FORMAT_BUFFER Sets the size of the buffer space needed fo expansion. 


REGDATA, which is the main macro used in the registration table, passes string data in 
its arguments. The REGFORMAT, REGDOCFLAG, REGICON, REGSTATUS, and 
REGVERBOPT macros format numeric values as string values. 


See the ObjectWindows Programmer's Guide for a list of which item names (referred to as 
keys) are required in the application and document registration tables. For information 
about how to use these macros in your OLE-enabled applications, see the sections on 
"Registering a linking and embedding server’ and "Registering the container” in the 
ObjectWindows Programmer’s Guide. The sample applications, REGTEST.CPP and 
STEP15DV.CPP, on your distribution disk, provide examples of registration tables 
designed for different kinds of applications and documents. 


See also END_REGISTRATION Macro, BEGIN _ REGISTRATION Macro, 
TLocaleString | 


BEGIN_REGISTRATION(regname) 

Indicates the beginning of a registration macro table. The macro takes one argument 
(regname), which is the name of the structure to be built. Within the registration table 
macro, there are several macros that build the registration structure. Depending on the 
type of application or document, different macros are used. The following example 
from STEP15.CPP, registers the crawane pad as a server appncadon and builds an 
Appkeg structure: 


BEGIN_REGISTRATION (AppReg) 
REGDATA(clsid, "{5E4BD320-8ABC-101B-A23B- ~CH4E85D07ED2} ") 
REGDATA (description, "OWL Drawing Pad Server") 
END_REGISTRATION . 


See also END REGISTRATION macro, REGDATA macro 
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END REGISTRATION macro 


END_REGISTRATION 

END_REGISTRATION Indicates the end of a registration macro table. You can insert 
the registration macros within the BEGIN_REGJSTRATION and 
END_REGISTRATION macros to build a registration structure. 


See also BEGIN REGISTRATION macro 


REGDATA macro locale.h 
REGDATA\var,val) _ 


The main registration macro, REGDATA registers information about an application or a 
document. The macro always takes an item name (for example, clsid) and a 
corresponding string value (for example, 5E4BD320-8ABC-101B-—A23B-— 
CE4E85D07ED2). The following example from STEP15.CPP on your distribution disk, 
passes the class ID and description to build an AppReg application registration structure: 


BEGIN_ REGISTRATION (AppReg) | 
REGDATA(clsid, "{5B4BD320-8ABC-101B-A23B-CE4E85D07ED2 }") 
REGDATA (description, "OWL Drawjng Pad Server") 

END_REGISTRATION 


For an automation server, the registration structure includes the following REGDATA 
macros: 


BEGIN_REGISTRATION (myappreg) 


REGDATA(clsid, "{01234567-1234-5678-1122-334455667788}") 
REGDATA (progid, "MySample") 

REGDATA (description, "My Sample 1.0 Application") 

REGDATA (cmdline, "/automation") 

REGDATA (version, va 


END_REGISTRATION 


Each automatable object requires a program ID, a description, and a command-line 
argument, which is placed on the server's command line. As usual, only one class ID is 
defined for the application. See the ObjectWindows Programmer's Guide for detailed 
information about how to register an automation server. 


For each application registration structure, you may have one or more document 
registration structures. The following example uses the data from several REGDATA 
macros to build a DocReg registration structure. 


BEGIN_REGISTRATION (mydocreg) 

REGDATA (description, "My Sample 1.0 Document") 

REGDATA(extension, ‘“myd") //Do not use a period before the extension. 
REGDATA(directory, "C:\temp") 

REGDATA(docfilter, "*.drw;*.drx") 

..//Insert additional macros here. 

REGDATA(debugger,  "tdw -t") // Sets debugger option 

REGDATA(progid, | "“MyDocument") //For servers only 

REGDATA (menuname, "My Document") //For servers only 
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REGITEM macro 


REGDATA(insertable,0) // For servers only 

REGDATA (usage, ocrMultipleUse) // For servers only 
REGDATA (verb0, "SEdit") //For servers only 
( 


REGDATA(verbl1, "SOpen") //For servers only 
REGDATA(verb2, "&Play") //For servers only 


...//Ingsert additional macros here. 
END REGISTRATION 


See also BEGIN REGISTRATION macro, END_REGISTRATION macro 


REGITEM(key,val) | | | 
The REGITEM macro lets you write customized entries for the system registry. The 
following example, from REGTEST.CPP, registers conversion formats. 


REGITEM ("CLSID\\<clsid>\\Conversion\\Readable\\Main", "FormatX,FormatY") 


The first string is the registry key which has one parameter (<clsid>) When the registry 
information is generated, an actual value is substituted for the template parameters. 


See also BEGIN REGISTRATION macro, END_REGISTRATION macro 


REGFORMAT macro 7 —__locale.h 


REGFORMAT(if,a,t,d) 
The REGFORMAT macro indicates the data formats the server or container can support 
and has the following parameters: 


i Order of priority for the designated data format with 0 being the highest fidelity rendered. 
f The data format, for example, ocrText, ocrTiff, ocrDib, and so on. 
a The format used to present the data. 


t Medium to use to transfer the data, for example, ocrMfPict (METAFILEPICT structure), ocrGDI (GDI 
object such as a bitmap), ocrIStream (Stream object in a compound file) and so on. 


d Whether or not data is provided as well as received in the designated format. The accepted values are 
ocrGet (imports data in the specified format), ocrSet (exports data in the specified format), or ocrGetSet 
(both exports and imports data in the specified format). 


For example, STEP1I5DV.CPP registers the following clipboard formats: 
REGFORMAT(1, ocrMetafilePict, ocrcontent, ocrMf£Pict, ocfSet) 


and generates the string, "formatl1, 3, 1, 1056,1." Although you could enter the string of 
numbers, it is much easier to use the enumerated values. See the ocrxxxx Clipboard 
constants for a description of the accepted data formats. 


To build a registration structure, use REGFORMAT within the 
BEGIN_REGISTRATION and END_REGISTRATION macros in a registration macro 
table. Any formats registered using REGFORMAT are also registered automatically on 
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REGSTATUS macro 
the Windows Clipboard. You can register your own formats by inserting a string 
indicating your own format. For example, 

REGFORMAT (2, "ANewFormat", ocrContent, ocrIStorage, ocrGetSet) 


To provide names for your own formats, call TOleFrame::AddUserFormatName. This 
function associates a clipboard data format with the description of the data format as it 
appears to users in the Help text of the Paste Special dialog box. 


See also BEGIN_REGISTRATION macro, ocrxxxx Clipboard constants, ocrxxxx 
medium constants, TOleFrame::AddUserFormatName 


REGSTATUS(a,f) 
The REGSTATUS macro indicates the way in which the view (referred to as the 
aspect") of an object behaves and has the following arguments: 


a The content of the object. 


- One of the ocrxxxx Object Status enum values indicating the status of the object, for example, 
ocrOnlyIconic, ocrActivateWhenVisible, and so on. 


The object can be defined as having many different aspects of behavior. For example, an 
object registered as ocrActivateWhen Visible is active whenever it is visible. 


Servers that support linked and embedded objects use this macro to register the 
behavior an object exhibits when it is viewed. This behavior is referred to as the aspect 
status or simply aspect of the object. 


The sample program, REGTEST.CPP, on your distribution disk includes the following 
REGSTATUS macros: 


REGSTATUS (all, ocrNoSpecialRendering) 
REGSTATUS (icon, ocrOnlyIconic) 


The first macro registers flags for all aspects of the object while the second macro 
registers flags for the iconic aspect of the object. (The icon used in the REGSTATUS 
macro must have been defined and registered.) 


See also BEGIN REGISTRATION macro, REGICON macro, ocrxxxx object status 
constants 


REGVERBOPT (v,mf,sf) 
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REGICON macro 


Registers the actions a server can perform on its objects. The arguments control how the 
verbs appear on the container's menu. The macro has the following arguments: 


v The verb key, for example, verb1 or verb2. 


mf A value that describes how a server's verbs appear on the container's menu. This value must be one of 
the ocrxxxx Verb Menu constants, for example, ocrGrayed, which makes the verb appear gray on the 
menu and disables the verb. 


sf A value that tells the container how to use the verb. This value must be one of the ocrxxxx Verb Attribute 
- constants, for example, ocrNeverDirties, which indicates that the verb never modifies the object. These 
options can be ORed together. 


The sample program, REGTEST.CPP, on your distribution disk includes the following 
REGVERBOPT macro: 


REGVERBOPT (verb1, ocrGrayed, ocrOnContainerMenu | ocrNeverDirties) 


These verb options are optional and are only valid if the verb is registered in the 
document registration table for the server application. To register the verb, use 


REGDATA(verb1, "&Open") 


See also BEGIN REGISTRATION macro, ocrxxxx verb attribute constants, ocrxxxx 
verb menu constants 


REGICON macro | locale.h 
REGICON() 


Registers an icon so that the object is displayed as an icon. The sample program, 
REGTEST.CPP, on your distribution disk, includes the following REGICON macro: 


-REGICON(1) 


The macro takes one argument, the index of the default icon to use. This argument 
indicates which icon is to be retrieved from the resource file when the document is 
displayed as an icon. 


~Seealso BEGIN REGISTRATION macro 


REGDOCFLAGS macro toca 
REGDOCFLAGS(i) 


Indicates options for the document and defines the characteristics of document 
templates. The REGDOCFLAGS arguments tell the document manager how to display 
and manage the documents and views. Although, for backward compatibility, you can 
still pass this information to the document template using the separate parameters in the 
constructor, newer programs should use the REGFORMAT, REGDOCFLAGS, and 
REGDATA macros to create a document template object. 


The sample program, REGTEST.CPP, on your distribution disk, includes the following 
REGDOCFLAGS macro declaration within the document registration structure: 
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REGISTRATION FORMAT _BUFFER macro 


BEGIN REGISTRATION (mytpl reg) 

REGDATA (description, "My Sample Draw View") 

REGDATA (filter, WE CW cre) 

REGDATA (defaultext, "dvw") 

REGDATA(directory, 0) 

REGDOCFLAGS (dtAutoDelete | dtUpdateDir | dtCreatePrompt) 
END_REGISTRATION 


The arguments to REGDOCFLAGS define the document's characteristics. In the case of 
dtAutoDelete, for example, the document is deleted when the last view is deleted. 


Certain documents must be registered with different options. For example, to register a 
Doc/View application used with a TOleDocument object, you must specify the 
dtRegisterExt and dtAutoOpen flags. If this is a Doc/View application, and if the 
document template is not hidden, you must register the description, filter, and 
extension. 


See also BEGIN REGISTRATION macro, REGFORMAT macro, REGDATA macro, 
dt document template constants 


REGISTRATION. FORMAT BUFFER(n); 

Allocates space in memory (1) for the expansion of the values passed in the registration 
macros that control the formatting of a document or application. Generally, allow 10 
bytes for each value passed in the REGFORMAT macro in addition to the space 
required for strings passed in the REGSTATUS, REGVERBOPT, REGICON, or 
REGFORMAT macros. For example, the sample program, STEP15.CPP uses this macro 
to declare 100 bytes of space: 


REGISTRATION FORMAT BUFFER (100) ; 
See also REGFORMAT macro, REGSTATUS macro 


TDocTemplate class doctpl.h 


TDocTemplate is an abstract base class that contains document template functionality. 
This document template class defines several functions that make it easier for you to use 
documents and their corresponding views. TDocTemplate classes create documents and 
views from resources and handle document naming and browsing. The document 
manager maintains a list of the current template objects. Each document type requires a 
separate document template. 


Public member functions 
ClearFlag | 


void ClearFlag(long flag); | 
Clears a document template constant. 
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TDocTemplate class 


See also dt document template constants 


Clone 
virtual TDocTemplate* Clone(TModule* module, TDocTemplate*® phead= DocTemplateStaticHead) = 0; 
Makes a copy of a document template. 


ConstructDoc 

virtual TDocument* ConstructDoc(TDocument* parent = 0) = 0; 

A pure virtual function that must be defined in a derived class, ConstructDoc creates a 
document specified by the document template class. Use this function in place of 
CreateDoc. 


See also TDocManager::CreateDoc 


ConstructView 

virtual TView* ConstructView(TDocument& doc = 0) = 0; 

A pure virtual function that must be defined in a derived class, Construct View creates the 
view specified by the document template class. 


Seealso TDocManager::CreateView 


CreateDoc 

virtual TDocument* CreateDoc(const char far* path, long flags = 0)= 0; 

An obsolete pure virtual function that must be defined in a derived class, CreateDoc 
creates a document based on the directory path (path) and the specified template and 
flags value. If the path is 0 and the new flag (dtNewDoc) is not set, the dialog box is 
displayed. This function is obsolete: use ConstructDoc instead. 


See also TDocManager::CreateAnyDoc, TDocTemplate::ConstructDoc 


CreateView 

virtual TView* CreateView(TDocument& doc, long flags) = 

A pure virtual function that must be defined in ina derived class, CreateView creates the 
view specified by the document template class. This function is obsolete: use 
Construct View instead. 


See also TDocManager::CreateAny View, TDocTemplate::ConstructView 


GetDefaultExt 

const char far* GetDefaultExt() const; 

Gets the default extension to use if the user has entered the name of a file without any 
extension. If there is no default extension, GetDefaultExt contains 0. 


GetDescription 

const char far* GetDescription() const; | | 

Gets the template description to put in the file-selection list box or the File | New menu- 
selection list box. 


GetDirectory 

const char far* GetDirectory() const; 

Gets the directory path to use when searching for matching files. This will get ere if 
a file is selected and the dtUpdateDir flag i is set. 
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TDocTemplate class 


See also 


GetDocManager 
TDocManager* GetDocManager() const; 
Points to the document manager. 


GetFileFilter 
const char far* GetFileFilter() const; 
Gets any valid document matching pattern to use when searching for files. 


GetFlags 

long GetFlags() const; 

Gets the document template constants, which indicate how the document is created and 
opened. 


See also dt xxxx document template constants 


GetModule 
TModule*& GetModule(); 
Returns a module pointer. 


GetNextTemplate 
TDocTemplate* GetNextTemplate() const; 
Gets the next template in the list of templates. 


GetRegList 

TRegList& GetRegList() const; 

Gets the program's registration table, which contains the program's current program ID, 
class ID, executable path, as well as other attributes used to construct a TDocTemplate 
object. See the entry for Registration macros in this manual for information about how 
the registration macros generate registration information. 


GetViewName 

virtual const char far* GetViewName() = 0; 

A pure virtual function that must be defined in a derived class, GetViewName gets the 
name of the view associated with the template. 


InitDoc 

TDocument* InitDoc(TDocument* doc, const char far* path, long flags); 

InitDoc is called only from the subclass so that CreateDoc can continue its document 
processing. 


Seealso TDoclemplate::CreateDoc 


InitView 
TView* InitView(TView* view); 
Called only from the subclass to continue CreateView processing. 


Seealso TDocIemplate::CreateView 


IsFlagSet 
bool IsFlagSet(long flag); 
Returns nonzero if the document template flag is set. 
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TDocTemplate class 


See also dis xxxx document template constants | 


IsMyKindOfDoc , 

virtual TDocument* IeMyKindOfDoc(TDocument® doc)=0; 

A pure virtual function that must be defined ina derived class, IsMyKindOfDoc tests if 
the template belongs to the same class as the document or to a derived class. 


Seealso TDocTemplateT::IsMyKindOfDoc 


IsMyKindOfView 

virtual TView* IsMyKindOfView(TView& view) = 0; 

A pure virtual function that must be defined in a derived class, IsMyKindofVi jew tests if 
the template belongs to the same class as the view or to a derived class. 


IsStatic 
bool IsStatic(); 
Returns true if the template is statically eoncticied: 


IsVisible 

bool IsVisible(); 

Indicates whether the document can be disslayed in the file selection dialog box. A 
document is visible if dtHidden isn't set and Description isn't 0. 


SelectSave 
bool SelectSave(TDocument& doc); 
Prompts the user to select a file name for the document. Filters out read-only files. 


SetDefaultExt 

void SetDefaultExt(const char far*); 

Sets the default extension to use if the user has entered the name of a file without any 
extension. If there is no default extension, SetDefaultExt contains 0. 


SetDirectory ? 

void SetDirectory(const char far’); 

void SetDirectory(const char far*, int len); 

Sets the directory path to use when searching for matching files. This will get updated if 
a file is selected and the dtUpdateDir flag is set. 


Seealso TDocTemplate::GetDirectory 


SetDocManager 
void SetDocManager(TDocManager* dm); 
Sets the current document manager to the argument dm. 


SetFileFilter 
void SetFileFilter(const char far*); 
Sets the valid document matching pattern to use when searching for files. 


SetFlag 

void SetFlag(long flag); 

Sets the document template constants, which indicate how the document is created and 
opened. 
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TDocTemplateT<D,V> class 


Seealso dtxxxx document template constants 


SetModule 
TModule*& SetModule(); 
Sets a module pointer. 


Protected constructor and destructor 


Constructor 

TDocTemplate(TRegList& regList, TModule*& module, TDocTemplate*& phead): 

Uses the information in the registration table (regList) to construct a TDocTemplate with 
the specified file description, file filter pattern, search path for viewing the directory, 
default file extension, and flags representing the view and creation options from the 
registration list. Then, adds this template to the document manager's template list. If the 
document manager is not yet constructed, adds the template to a static list, which the 
document manager will later add to its template list. 


The argument, module, specifies the TModule of the caller. phead specifies the template 
head for the caller's module. See the Registration macros entry in this manual for 
information about the registration macros that generate a TRegList, which contains the 
attributes used to create a TDocTemplate object. 


Destructor 

~TDocTemplate(); 

Destroys a TDocTemplate object and frees the data members (FileFilter, Description, 
Directory, and DefaultExt). The Destructor is called only when no views or documents are 
associated with the template. Instead of calling this Destructor directly, use the Delete 
member function. 


See also} dtxxxx document template constants 


To register the associated document and view classes, a parameterized subclass, 
TDocTemplateT<D,V>, is used to construct a particular document and view, where D 
represents the document class and V represents the view class. The parameterized 
template classes are created using a macro, which also generates the associated 
streamable support. The document and view classes are provided through the use of a 
parameterized subclass. The template class name is used as a typedef for the 
parameterized class. For example, 


DEFINE_DOC_TEMPLATE_CLASS(TFileDocument, TEditView, MyEditFile) 


You can instantiate a document template ung either a static member or an explicit 
construction. For example, 


MyEditFile etl("Edit text files", 
Me EXE" "Ds \ doe", "sTXT"", dtNoAUutoVirew) ; 
new MyEditFile(..... ) 
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TDocTemplateT<D,V> class 


Form 1 


Form 2 


When a document template is created, the document manager (TDocManager) registers 
the template. When the document template's delete function is called to delete the © 
template, it is no longer visible to the user. However, it remains in memory as long as 
any documents still use it. 


Public constructors 


Constructors | 
TDocTemplateT (const char far* filt, const char far* desc, const char far* dir, const char far* ext, 

long flags = 0, TModule*& module = ::Module, TDocTemplate*& phead = DocTemplateStaticHead); 
Constructs a TDocTemplateT with the specified file description (desc), file filter pattern 
(filt), search path for viewing the directory (dir), default file extension (ext), and flags 
representing the view and creation options (flags). module, which is instantiated and 
exported directly from every executable module, can be used to access the current 
instance. 


TDocTemplateT(TRegList& regList, TModule*& module = ::Module, 

TDocTemplate*& phead = DocTemplateStaticHead); 
Constructs a TDocTemplateT using the registration table to determine the file filter 
pattern, search path for viewing the directory, default file extension, and flag values. See 
the entry in this manual for registration macros for more information about how the 
registration tables are created. module, which is instantiated and exported directly from 
every executable module, can be used to access the current instance. 


Public member functions 


Clone 
TDocTemplateT* Clone(TModule* module, TDocTemplate*& phead = DocTemplateStaticHead; 
Makes a copy of the TDocTemplateT object. 


CreateDoc 

D* CreateDoc(const char far* path, long flags = 0); 

CreateDoc creates a document of type D based on the directory path (path) and flags 
value. 


Seealso TDocTemplate::CreateDoc 


CreateView 
TView* CreateView(TDocumenté& doc, long flags = 0); 
CreateView creates the view specified by the document template class. 


Seealso T’DocManager::CreateAny View 


IsMyKindOfDoc 

D* IsMyKindOfDoc(TDocument& doc); 

IsMyKindOfDoc tests to see if the document (doc) is the same class as the template’ S 
document class or if the document is a derived class. If the template can't use the 
document, IsMyKIndOfDoc returns 0. 


Seealso TDocTemplate::IsMyKindOfDoc 
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TDropInfo class 


IsMyKindOfView 

V* IsMyKindOfView(TView& view); 

IsMyKindOfView tests to see if the view (view) is the same class as the template's view 
class or if the view is a derived class. If the template can't use the view, IsMyKIndOfView 
returns 0. 


GetViewName 
virtual const char far* GetViewName(); 
Get ViewName gets the name of the view associated with the template. 


TDropInfo class geometry.h 


TDropInfo is a simple class that supports filename drag and drop operations using the 
WM_DROPFILES message. Each TDropInfo object has a private handle to the HDROP 
structure returned by the WM_DOPFILES message. 


Public constructor 


Constructor 
TDropInfo(HDROP handle); 
Creates a TDropInfo object with Handle set to the given handle. 


Public member functions 


DragFinish 

void DragFinish(); 

Releases any memory allocated for the transferring of this TDropInfo object's files during 
drag operations. 


DragQueryFile 

uint DragQueryFile( uint index, char far* name, uint nameLen) 

Retrieves the name of the file and related information for this 1 object. If index is set to -1 
(OxXFFFF), DragQueryFile returns the number of dropped files. This is equivalent to 
calling DragQueryFileCount. 


If index lies between 0 and the total number of dropped files for this object, 
Drag QueryFile copies to the name buffer (of length nameLen bytes) the name of the 
dropped file that corresponds to index, and returns the number of bytes actually copied. 


If name is 0, DragQueryFile returns the required buffer size (in bytes) for the given index. 
This is equivalent to calling DragQueryFileNameLen. 


See also TDropInfo::DragQueryPoint, TDropInfo::DragQuery FileCount 
DragQueryFileCount 
uint DragQueryFileCount(); 


Returns the number of dropped files in this TDropInfo object. This call is equivalent to 
calling DragQueryFile(-1, 0, 0). 
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TLangld typedef 
See also TDropInfo::DragQueryFile 7 


DragQueryFileNameLen 

uint DragQueryFileNameLen(uint index) 

Returns the length of the name of the file in this TDropInfo object corresponding to the 
given index. This call is equivalent to calling DragQueryFile(index, 0, 0). 


Seealso $TDropInfo::DragQueryFile 


DragQueryPoint 

bool DragQueryPoint(TPoint& point) 

Retrieves the mouse pointer position when this object's files are dropped and copies the | 
coordinates to the given point object. point refers to the window that received the 
WM_DROPFILES message. DragQueryPoint returns true if the drop occurs inside the 
window's client area, otherwise false. 


Seealso TPoint class 


HDROP() 
operator HDROP(); 
Typecasting operator that returns Handle. 


TLangld typedef : locale.h 


typedef unsigned short TLangld; | 

Holds a language ID, a predefined minis that represents a base language and dialect. 
For example, the number 409 represents American English. TLocaleString uses the 
language ID to find the correct translation for strings. 


Seealso TLocaleString 


TPoint class | geometry.h 


TPoint is a support class, derived from tagPOINT. Under Win32, the latter is defined as 


typedef struct tagPOINT { 
int x; 
int y; 
bi | 
TPoint encapsulates the notion of a two-dimensional point that usually represents a 
screen position. TPoint inherits two data members, the coordinates x and y, from 
tagPOINT. Member functions and operators are provided for comparing, assigning, and 
manipulating points. Overloaded << and >> operators are declared as friends of TPoint, 
allowing chained insertion and extraction of TPoint objects with streams. 
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Form 1 


Form 2 


Form 3 


Form 4 


Form 5 


TPoint class 


Public constructors 


Constructors 

TPoint(); 

The default TPoint constructor. 

TPoint(int x, int _ y); 

Creates a TPoint object with the given coordinates. 


TPoint(const POINT& point); 
Creates a TPoint object with x = point. x y = point.y. 


TPoint(const SIZE& size); | 
Creates a TPoint object with x = size.cx and y = size.cy. 


TPoint(uint32 dw); 
Creates a TPoint object with x = LOWORD(dw) y = HIWORD(dw)). 


Seealso TPOINT, TSIZE 


Public member functions 


Offset 

TPoint& Offset(int dx, int dy); 

Offsets this point by the given delta arguments. This point is changed to (x + dx, y + dy). 
Returns a reference to this point. 


Seealso TPoint::OffsetBy, TPoint::operator += 


OffsetBy 

TPoint OffsetBy(int dx, int dy) const; 

Calculates an offset to this point using the given displacement arguments. Returns the 
point (x + dx, y + dy). This point is not changed. | 


Seealso 'Point::operator +, TPoint::Offset 


operator + 

TPoint operator +(const TSize& size) const; 

Calculates an offset to this point using the given size argument as the displacement. 
Returns the point (x + size.cx, y + size.cy). This point is not changed. ! 


Seealso T’Point::OffsetBy, TSize class 


operator — 

TPoint operator —(const TSize& size) const; 

TSize operator —(const TPoint& point) const; 

TPoint operator —() const; 

The first version calculates a negative offset to this point using the given size argument 
as the displacement. Returns the point (x —size.cx, y — size.cy). This point is not changed. 


The second version calculates a distance from this point to the point argument. Returns 
the TSize object (x — point.x, y — point.y). This point is not changed. 


The third version returns the point (-x, -y). This point is not changed. 
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See also TPoint: seperitor +, TSize class 


operato = | 
bool operator ==(const TPoint& other) const; 
Returns true if this point is equal to the other point; otherwise returns false. 


See also TPoint::operator != 


operator += 

TPoint& operator +=(const TSize& size); 

Offsets this point by the given size argument. This point is changed to(x + size.cx, y + 
size.cy). Returns a reference to this point. 


Seealso TPoint::Offset, TPoint::operator —=, TSize class 


operator —= 

TPoint& operator —=(const TSize& size); 

Negatively offsets this point by the given size argument. This point is changed to (x — 
size.cx, y — size.cy). Returns a reference to this point. 


Seealso TPoint::Offset, TPoint::operator +=, TSize class 


operator != 
bool operator !=(const TPoint& other) const; 
Returns false if this point is equal to the other point; otherwise returns true. 


Seealso TPoint::operator == 


operator >> 

Form1  ipstream& operator >>(ipstream& is, TPoint& p); 
Extracts a TPoint object from persistent stream is, and copies it to p. Returns a reference 
to the resulting stream, allowing the usual chaining of << operations. 


Form2 _ istream& operator >>(istream& is, TPoint& p); 
Extracts a TPoint object from stream is, and copies it to p. Returns a reference to the 
resulting stream, allowing the usual chaining of >> operations. 


Seealso TPoint operator <<, class ipstream 


operator << 

Form1  opstream& operator <<(opstream& os, const TPoint& p); 
Inserts the given TPoint object p into persistent stream os. Returns a reference to the 
resulting stream, allowing the usual chaining of >> operations. 


Form2 ostream& operator <<(ostream& os, const TPoint& p); 
Formats and inserts the given TPoint object p into the ostream os. The format i is "(x,y)". 
Returns a reference to the resulting stream, allowing the usual chaining of << 
operations. 


Seealso Point operator >>, ostream 
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Form 1 


Form 2 


Form 1 


Form 2 


A small utility class that provides automatic destruction for objects constructed using 
new. |’Pointer is a parameterized class that holds a pointer to its parameterized type and 
overloads operators to behave like an object pointer. Assigning a pointer to a TPointer 
object eventually causes the object to be deleted when the function exits or when a 
TPointer goes out of scope or when another pointer is assigned to the same object. A 
TPointer object can be instantiated using one of the following equivalent methods: 


TPointer<SomeClass> p = new SomeClass; 
TPolnter<SomeClass> p(new SomeClass); 
TPointer<SomeClass> p; p = new SomeClass; 


To remove the object, assign 0 to the pointer. 


Public constructors 


Constructors 
TPointer() : TPointerBase<T>(); 
Default constructor in which p is initialized to 0. 


TPointer(T* pointer) : TPointerBase<T>(pointer); 
Initialized constructor where p is initialized to pointer. 


Public member functions 


operator * 

T& operator *(); 

Overloaded type conversion operator that casts its argument to a pointer to the type 
passed in. 


operator I* 

operator T*(); 

Overloaded type conversion operator that allows the TPointer object to be passed as a 
function argument or assigned to a variable as if it were a pointer. 


operator = 

T* operator =(T* src); 

Assignment operator T™ is assigned to p. 
T* operator =(const TPointer<T>& src); 


Assignment operator used when r is a const reference to TPointer of T. This operator 
saves converting if another pointer object is used. 


Operator —> 
T* operator —>(); 
Provides access to the pointer. 
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_ TProcinstance class == — ~— geometry.h 


Designed for Win16 applications, T’ProcInstance handles creating and freeing an instance 
thunk, a piece of code created for use with exported callback functions. (A callback 
_ function is a function that exists within a program but is called from outside the 
- program by a Windows library routine, for example, a dialog box function.) 


For Win32 applications, TProcInstance is non-functional. The address returned from 
TProcInstance can be passed as a parameter to callback functions, window subclassing 
functions, or Windows dialog box functions. 


See the Windows API online Help for more information about MakeProcInstance, which 
creates an instance thunk for the function and FreeProcInstance, which frees an instance 
thunk. For more information about exporting callback functions, see the Borland C++ 
Programmer's Guide. 


Public constructor and destructor 


Constructor 

TProcinstance(FARPROC p); 

Makes a TProcInstance, passing p as the address of the procedure. Under Win16, calls 
:;MakeProcInstance to make an instance thunk for p. Under Win32, the constructor just 
saves p. 


Destructor 
~TProclnstance() 
Under WIN16 frees the instance eee 


See also ::MakeProclInstance (Windows API), ::FreeProcInstance (Windows API) 


Public member function 


FARPROC() 
operator FARPROC(); | 
Under WIN16, returns the instance thunk. Under Win32, returns p from the constructor. 


TRect class ~— geometry.h 


TRect is a mathematical class derived from tagRect. The tagRect struct is defined as 


struct tagRECT { 
int left; 
Int top; 
Ime Tighe: 
int bottom; 


i 


TRect encapsulates the properties of rectangles with sides parallel to the x- and y-axes. In 
ObjectWindows, these rectangles define the boundaries of windows, boxes, and 
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TRect class 


clipping regions. TRect inherits four data members from tagRect left, top, right, and 
bottom. These represent the top left and bottom right (x, y) coordinates of the rectangle. 
Note that x increases from left to right, and y increases from top to bottom. 


TRect places no restrictions on the relative positions of top left and bottom right, so it is 
legal to have left > right and top > bottom. However, many manipulations—such as 
determining width and height, and forming unions and intersections—are simplified by 
normalizing the TRect objects involved. Normalizing a rectangle means interchanging 
the corner point coordinate values so that left < right and top < bottom. Normalization 
does not alter the physical properties of a rectangle. myRect.Normalized creates 
normalized copy of myRect without changing myRect, while myRect.Normalize changes 
myRect to a normalized format. Both members return the normalized rectangle. 


TRect constructors are provided to create rectangles from either four ints, two TPoint 
objects, or one TPoint and one TSize object. In the latter case, the TPoint object specifies 
the top left point (also known as the rectangle's origin) and the TSize object supplies the 
width and height of the rectangle. Member functions perform a variety of rectangle tests 
and manipulations. Overloaded << and >> operators allow chained insertion and 
extraction of T’Rect objects with streams. 


Public constructors 


Constructors 
TRect(); 
The default constructor. 


TRect(const RECT far& rect); 
Copies the given rect to this object. 


TRect(int left, int_top, int right, int_bottom); 
Creates a rectangle with the given values. 


TRect(const TPoint& upLeft, const TPoint& loRight); 
Creates a rectangle with the given top left and bottom right points. 


TRect(const TPoint& origin, const TSize& extent); 
Creates a rectangle with its origin (top left) at origin, width at extent.cx, height at 
extent.cy. 


Seealso Point class, TSize class 


Public member functions 


Area 
long Area() const; 
Returns the area of this rectangle. 


Seealso TRect::Size 


BottomLeft 
TPoint BottomLeft() const; 
Returns the TPoint object representing the bottom left corner of this rectangle. 
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Seealso  J'Rect:'TopLeft, TRect: TopRight, TRect: BottomRight, TPoint 
BottomRig ht 


_const TPoint& BottomRight() const; 
TPoint& BottomRight(); 


Returns the TPoint object representing the bottom right corner of this rectangle. 
Seealso TRect::TopRight, TRect::BottomLeft, TRect::TopLeft, TPoint class 


BottomRight 

const TPoint& BottomRight() const; 

TPoint& BottomRight(); 

Returns the TPoint object representing the bottom right corner of this rectangle. 


Seealso TRect::TopRight, TRect::BottomLeft, TRect::TopLeft, TPoint class 


Contains 

bool Contains(const TPoint& point) const; 

Returns true if the given point lies within this cecencls otherwise, it returns false. If _ 
point is on the left vertical or on the top horizontal borders of the rectangle, Contains also 
returns true, but if point is on the right vertical or bottom horizontal borders, Contains 
returns false. 


bool Contains(const TRect& other) const; 
Returns true if the other rectangle lies on or within this rectangle; otherwise, it returns 
false. 


Seealso TRect::Touches, TPoint class, TRect class 


Height 
int Height() const; 
Returns the height of this rectangle (bottom — top). 


See also TRect::Width 


Inflate 

TRect& Inflate(int dx, int dy); 

TRect& Inflate(const TSize& delta); 

Inflates a rectangle inflated by the given delta arguments. In the first version, the top left 
corner of the returned rectangle is (left — dx, top — dy), while its bottom right corner is 
(right + dx, bottom + dy). In the second version the new corners ate (left — size.cx, top — 
size.cy) and (right + size.cx, bottom + size.cy). 


Seealso TRect class, TSize class 


InflatedBy 

TRect InflatedBy(int dx, int dy) const; 

TRect InflatedBy(const TSize& size) const; 

Returns a rectangle inflated by the given delta arguments. In the first version, the top left 


corner of the returned rectangle is (left — dx, top — dy), while its bottom right corner is 


(right + dx, bottom + dy). In the second version the new corners are (left — size.cx, top — 
size.cy) and (right + size.cx, bottom + size.cy). The calling rectangle object is unchanged. 


Seealso TRect::OffsetBy, TRect class, TSize class 
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IsEmpty 
bool IsEmpty() const; 
Returns true if left >= right or top >= bottom; otherwise, returns false. 


Seealso TRect::SetEmpty, TRect::IsNull 


IsNull 
bool IsNull() const; 
Returns true if left, right, top, and bottom are all 0; otherwise, returns false. 


Seealso TRect::IsEmpty, TRect::SetEmpty 


Normalize 

TRect& Normalize(); 

Normalizes this rectangle by switching the left and right data member values if left > 
right, and switching the top and bottom data member values if top > bottom. Normalize 
returns the normalized rectangle. A valid but nonnormal rectangle might have left > 
right and/or top > bottom. In such cases, many manipulations (such as determining 
width and height) become unnecessarily complicated. Normalizing a rectangle means 
interchanging the corner point values so that left < right and top < bottom. The physical 
properties of a rectangle are unchanged by this process. 


Seealso TRect::Normalized, TRect class 


Normalized 

TRect Normalized() const; 

Returns a normalized rectangle with the top left corner at (Min(left, right), Min(top, 
bottom)) and the bottom right corner at (Max(left, right), Max(top, bottom)). The calling 
rectangle object is unchanged. A valid but nonnormal rectangle might have left > right 
and/or top > bottom. In such cases, many manipulations (such as determining width and 
height) become unnecessarily complicated. Normalizing a rectangle means 
interchanging the corner point values so that left < right and top < bottom. The physical 
properties of a rectangle are unchanged by this process. 


Note that many calculations assume a normalized rectangle. Some Windows API 
functions behave erratically if an inside-out Rect is passed. 


Seealso TRect::Normalize, TRect 


Offset 

TRect& Offset(int dx, int dy); 

Changes this rectangle so its corners are offset by the given delta values. The revised 
rectangle has a top left corner at (left + dx, top + dy) and a right bottom corner at (right + 
dx, bottom + dy). The revised rectangle is returned. 


Seealso TRect::operator +, TRect::operator +=, TRect::OffsetBy 


OffsetBy 

TRect OffsetBy(int dx, int dy) const; 

Returns a rectangle with the corners offset by the given delta values. The returned 
rectangle has a top left corner at (left + dx, top + dy) and a right bottom corner at (right + 
dx, bottom + dy). 


Seealso 'Rect::operator + 
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sporaict + 

_ TRect operator +(const TSize& size) const: 
Returns a rectangle offset positively by the delta values given s size. The returned 
rectangle has a top left corner at (left + size.x, top + size.y) and a right bottom corner at 
(right + size.x, bottom + size.y). The calling a object is unchanged. | 


See also TRect: :OffsetBy, TSize class 


operator — 
-TRect operator -(const TSize& size) const; 

Returns a rectangle offset negatively by the delta values given size. The returned 
rectangle has a top left corner at (/eft — size.cx, top — size.cy) and a right bottom corner at 
(right — size.cx, bottom — size.cy). The calling rectangle object is unchanged. 


Seealso TRect::OffsetBy, TSize class 


operator & 

TRect operator &(const TRect& other). const; 

Returns the intersection of this rectangle and the other rectangle. The calling rectangle 
object is unchanged. Returns a NULL rectangle if the two don't intersect. 


Seealso T'Rect::operator |, TRect::operator &= 


operator | 

TRect operator I(const TRect& other) const; 

Returns the union of this rectangle and the other rectangle. The calling rectangle object is 
unchanged. 


Seealso TRect::operator &, TRect::operator |= 


operator == : 

bool operator ==(const TRect& other) const; 

Returns true if this rectangle has identical corner coordinates to the other ecanels 
otherwise, returns false. 


Seealso J Rect::operator != 


operator != 

bool operator !=(const TRect& other) const; 

Returns false if this rectangle has identical corner coordinates to the other rectangle; 
otherwise, returns true. 


Seealso ’Rect::operator == 

operator += 

TRect& operator +=(const TSize& delta); 

Changes this rectangle so its corners are offset by the given delta values, delta.x and 


delta.y. The revised rectangle has a top left corner at (/eft + delta.x, top + delta.y) and a right 
bottom corner at (right + delta.x, bottom + delta.y). The revised rectangle is returned. 


Seealso ‘Rect::operator +, TRect::OffsetBy, TRect::Offset 


operator -= 
-TRect& operator -=(const TSize& delta); 
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Changes this rectangle so its corners are offset negatively by the given delta values, 
delta.x and delta.y. The revised rectangle has a top left corner at (left — delta.x, top — delta.y) 
and a right bottom corner at (right — delta.x, bottom — delta.y). The revised rectangle is 
returned. 


Seealso TRect::operator -, TRect::operator +=, TRect::OffsetBy, TRect::Offset 


operator &= 

TRect& operator &=(const TRect& other); 

Changes this rectangle to its intersection with the other rectangle. This rectangle object is 
returned. Returns a NULL rectangle if there is no intersection. 


Seealso TRect::operator &, TRect::operator |= 


operator |= 

TRect& operator |=(const TRect& other); 

Changes this rectangle to its union with the other rectangle. This rectangle object is 
returned. 


Seealso TRect::operator |, TRect::operator &= 


operator >> 

ipstream& _BIDSFUNC operator >>(ipstreamé& is, TRect& r); 

Extracts a TRect object from is, the given input stream, and copies it to r. Returns a 
reference to the resulting stream, allowing the usual chaining of >> operations. 


Seealso ‘Rect operator << 


operator << 

opstream& _BIDSFUNC operator <<(opstream& os, const TRect& r); 

Inserts the given TRect object, r, into the opstream, os. Returns a reference to the resulting 
stream, allowing the usual chaining of << operations. 


ostream& _BIDSFUNC operator <<(ostream& os, const TRect& r); | 
Formats and inserts the given TRect object, r, into the ostream, os. The format is (r.left, 
r.top)(r.right, r.bottom). Returns a reference to the resulting stream and allows the usual 
chaining of << operations. 


See also ‘Rect operator >> 


operator TPoint*() 
operator const TPoint*() const; 
operator TPoint*() 


Type conversion operators converting the pointer to this rectangle to type pointer to 
TPoint. . 


Seealso TPoint class 


Set 
void Set(int _left, int _top, int _right, int _bottom); 
Repositions and resizes this rectangle to the given values. 


SetEmpty 
void SetEmpty(); 
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Empties this rectangle by setting left, top, right, and bottom to 0. 


SetNull 
void SetNull(); : 
Sets the left, top, right, and bottom of the rectangle to 0. 


Size 
TSize Size() const; 
Returns a TSize object representing the width and height of this ee ancie 


— See also TSize class 


TopLeft 
const TPoint& TopLeft() const; 
_ TPoint& TopLeft(); 


Returns the TPoint object representing the top left corner of this rectangle. 
Seealso T’Rect::TopRight, TRect::BottomLeft, TRect::BottomRight, TPoint class 


TopRight 
TPoint TopRight() const; 
Returns the TPoint object representing the top right corner of this rectangle. 


Seealso Rect: pel TRect::BottomLeft, TRect: ‘Botomiser 


Touches 

bool Touches(const TRect& other) const; 

Returns true if the other rectangle shares any interior points with this rectangle; 
otherwise, returns false. 


Seealso TRect::Contains 


Width 
int Width() const; 
Returns the width of this rectangle (right — left). 


Seealso T'Rect::Height 


TResid class | - geometry.h 


A simple support class, TResId creates a resource ID object from either an integer or an 
actual string identifier. For example, T’ResId encapsulates the use of LPSTR (char_far*) as 
a resource identifier. This resource identifier can be passed to various ObjectWindows 
classes. To handle these two different types of resource identifiers, TResId defines a 
conversion operator and provides two constructors that convert and use these native 
data types. One constructor accepts a 16-bit integer and the other accepts a character 

_ string. 
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Public constructors 


Constructors 
Formi  TResld(); 
The default TResId constructor. 


Form2 _TResid(int resNum); 
Creates a T’Resld object with the given resNum. 


Form3 TResld(const char far* resString); 
Creates a TResId object with the given resString. 


Public member functions 


char far* 

operator char far*(); 

Typecasting operator that converts Id (a TResId private data member) to type char far* 
so that instances of TResId can be used in places where char far* data types are expected. 


IsString 
bool IsString() const; 
Returns true if this resource ID was created from a string; otherwise, returns false. 


Friend functions 


operator >> 

friend ipstream& operator >>(ipstream& is, TResid& id); | 
Extracts a TResld object from is (the given input stream), and copies it to id. Returns a 
reference to the resulting stream, allowing the usual chaining of >> operations. 


Seealso TResId friend operator <<, ipstream 


operator << 

Form1 _ friend opstream& operator <<(opstream& os, const TResld& id); 
Inserts the given TResId object (id) into the opstream (os). Returns a reference to the 
resulting stream, allowing the usual chaining of << operations. 


Form2 _ friend ostreamé& operator <<(ostream& os, const TResidé id); 
Formats and inserts the given TResId object (id) into the ostream (os). Returns a reference 
to the resulting stream, allowing the usual chaining of << operations. 


Seealso TReslId friend operator >>, ostream, opstream 
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TSize is a mathematical class derived from the structure tagSIZE. 
The tagSIZE struct is defined as 


struct tagSIZE { 
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Tits ce 
int cy? 


}; 


TSize encapsulates the notion of a two-dimensional quantity that iaadiiy represents a 
displacement or the height and width of a rectangle. TSize inherits the two data _ 
members cx and cy from tagSIZE. Member functions and operators are provided for 
comparing, assigning, and manipulating sizes. Overloaded << and >> operators allow 
chained insertion and extraction of TSize objects with streams. 


Public constructors 


Constructors 
TSize(); 
The default TSize constructor. 


TSize(int dx, int dy); | | 
Creates a TSize object with cx = dx and cy = dy. 


TSize(const POINT& point); 


Creates a TSize object with cx = point.x and cy = point. y. 


TSize(const SIZE& size); 


Creates a TSize object with cx = size.cx and cy = size.cy. 


TSize(uint32 dw); 
Creates a TSize object with cx = LOWORD(dw) and cy = HIWORD(dw)). 


Seealso TPoint class, Size struct 


Public member functions 


Magnitude 

int Magnitude() const; 
Returns the length of the diagonal of the rectangle represented by this object. The value 
returned is an int approximation to the square root of (cx + cy). 


operator + 

TSize operator +(const TSize& size) const; 

Calculates an offset to this TSize object using the given size argument as the 
displacement. Returns the object (cx + size.cx, cy + size.cy). This TSize object is not 
changed. 


Seealso TSize::operator — 


operator - 

TSize operator —(const TSize& size) const; 

The first version calculates a negative offset to this TSize object using the given size 
argument as the displacement. Returns the point or siZe.cx, CY — size. Y This object is 
not changed. | 


TSize operator -() const; 
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The second version returns the TSize object (—cx, -cy). This object is not changed. 


Seealso T’Size::operator + 


operator == 
bool operator ==(const TSize& other) const; 
Returns true if this size object is equal to the other TSize object; otherwise returns false. 


Seealso Size::operator != 


operator != 
bool operator !=(const TSize& other) const; 
Returns false if this size object is equal to the other TSize object; otherwise returns true. 


Seealso TSize::operator == 


operator += 

TSize& operator +=(const TSize& size); 

Offsets this TSize object by the given size argument. This TSize object is changed to (cx.+ 
size.cx, cy + size.cy). Returns a reference to this object. | 


Seealso Size::operator —= 


operator —= 

TSize& operator —=(const TSize& size); 

Negatively offsets this TSize object by the given size argument. This object is changed to 
(cx — size.cx, cy — size.cy). Returns a reference to this object. 


Seealso ‘T'Size::operator += 


operator >> 

ipstream& operator >>(ipstream& is, TSize& s); 

Extracts a TSize object from is, the given input stream, and copies it to s. Returns a 
reference to the resulting stream, allowing the usual chaining of >> operations. 


Seealso Size operator <<, ipstream 


operator << 

Form1 opstreamé& operator <<(opstream& os, const TSize& s); 
Inserts the given TSize object (s) into the opstream (os). Returns a reference to the resulting 
stream, allowing the usual chaining of << operations. 


Form2  ostreamé operator <<(ostream& os, const TSize& s); 
Formats and inserts the given TSize object (s) into the ostream (os). The format is "(cx x 
cy)". Returns a reference to the resulting stream, allowing the usual chaining of << 
operations. 


Seealso Size operator >>, opstream, ostream 


TXBase class _ except.h 


Derived from xmsg, TXBase is the base class for ObjectWindows and ObjectComponents 
exception-handling classes. The ObjectWindows classes that handle specific kinds of 
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exceptions, for example out-of-memory or invalid window exceptions are derived from 
TXOuwl, which is in turn derived from TXBase. The ObjectComponents classes, TXOle 
and TXAuto, are derived directly from TXBase. 


TXBase contains the functions, Clone and Throw, which are overridden in all derived 
classes, as well as two constructors. The constructors increment, InstanceCount, TXBase’s 
public data member, and the destructor decrements InstanceCount. 


See the Borland C++ Library Reference for a description of xmsg, TXBase’s parent class. See 
the Object Windows Programmer's Guide for information about how to use TXBase in your 
applications. 


See also 


TXOwl 


- Public constructors and destructor 


Constructors 

TXBase(const string& msg); 

Calls the xmsg class's constructor that takes a string parameter and initializes xmsg with 
the value of the string parameter. 


TXBase(const TXBaseé& src); | 
Creates a copy of the TXBase object passed in the TXBase parameter. 


Destructor 
virtual ~ TXBase; 
Destroys the TXBase object and decrements the InstanceCount data member 


See also TXOwl public constructors and destructor 


Public data member 


InstanceCount 

static int InstanceCount; | 
Counts the number of TXBase and TXBase-derived objects existing in a single 
application. | 


Public member functions 


Clone 
virtual TXBase* Clone(); 
Makes a copy of the exception object. 


Throw 
virtual void Throw(); 
Throws the exception object. 
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This appendix includes several tables listing encapsulated Windows API functions that 
take an HWND as the first argument. The tables are organized in the following manner: 


Al 
A2 
A3 
AA 
AS 
AG 
AZ 
A8 
A9 
A.10 
All 
Al2 
A.13 
Al4 
AAS 


Inline HWND functions 
Windows messages 
Window dimensions 
Window properties 
Window placement 
Child window placement 

Window painting 

Using scrolling and scroll bars 
Parent and child windows with IDs 
Menus and menu bars 

Clipboard placement 

Timer operations 

Caret and cursor functions 
Registering hot keys 

Miscellaneous functions 


702 
702 
702 
703 
703 
703 
704 
704 
705 
705 
705 
705 
706 
706 


706 


Most of the encapsulated functions are implemented as inline functions that pass the 
HWindow member variable as the HWND argument. The remaining arguments are 
passed without changing their prototype. 


The other functions are static functions that return information regarding windows. 
These functions don't actually use HWindow as the argument because the HWND is 
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either iaplied or the function returns the HWND. An HWND that serves as a handle to 
an. window can be converted to a TWindow”* by using GetWindowPtr(). 


Note that in the scope of TWindow or derived class, all direct calls to the corresponding 
Windows versions of these functions must be globally scoped, as in ::SendMessage(). 


The functions in Table A.1 allow a TWindow to be used as a HWND in Windows API 
calls. 


Table A.1 Encapsulated inline HWND functions 


_ Senior 0 ae 
IsWindow BOOL IsWindow () const 


The functions in Table A.2 handle Window messages. 


Table A.2 — Encapsulated Window messages 


EnableWindow BOOL EnableWindow (BOOL enable) 

GetCapture static HWND GetCapture () 

GetFocus static HWND GetFocus () 

IsWindowEnabled BOOL IsWindowEnabled () const 

PostMessage BOOL PostMessage (UINT msg, WPARAM wParam = 0, LPARAM IParam = 0) 
const 

ReleaseCapture static void ReleaseCapture () 


SendDlgltemMessage LRESULT SendDlgltemMessage (int childId, UINT msg, WPARAM wParam =0, » 
LPARAM IParam = 0) const 


SendMessage LRESULT SendMessage (UINT msg, WPARAM wParam = 0, LPARAM IParam 
-=() const 

SetCapture HWND SetCapture () 

SetFocus HWND SetFocus () 


Table A.3 lists functions that adjust window coordinates and sizes. 


Table A.3 Window coordinates and dimensions 


J j (T 
AdjustWindowRectEx static void AdjustWindowRectEx (TRect& rect, DWORD style, BOOL menu, 
DWORD exStyle) 
ChildWindowFromPoint = HWND ChildWindowFromPoint (const TPointé& point) 
ClientToScreen void ClientToScreen (TPoint& point) const 
GetClientRect TRect GetClientRect () 
GetClientRect void GetClientRect (TRect& rect) 
GetWindowRect void GetWindowRect (TRect& rect) 7 
MapWindowPoints void MapWindowPoints (HWND hWndTo, TPoint *points, int count) const 
ScreenToClient void ScreenToClient (TPointé& point) const 


WindowFromPoint static HWND WindowFromPoint (const TPoint& point) 
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Table A.4 lists functions that encapsulate window properties and style attributes. 


Table A.4 Window pasae 
EnumProps int | aumProps (PROPENU MPROC sei 
GetClassLong long GetClassLong (int index) const 
GetClassName long GetClassName (char far* className, int maxCount) const 
GetClassWord WORD GetClassWord (int index) const 
GetProp HANDLE GetProp (const char far* str) const 
GetProp HANDLE GetProp (WORD atom) const 
GetWindowLong long GetWindowLong (int index) const 
GetWindowWord WORD GetWindowWord (int index) const 
RemoveProp HANDLE RemoveProp (const char far* str) const 
RemoveProp HANDLE RemoveProp (WORD atom) const 
SetClassLong long SetClassLong (int index, long newLong) 
SetClassWord WORD SetClassWord (int index, WORD newWord) 
SetProp BOOL SetProp (const char far* str, HANDLE data) const 
SetProp BOOL SetProp (WORD atom, HANDLE data) const 
SetWindowLong long SetWindowLong (int index, long newLong) 
SetWindowWord WORD SetWindowWord (int index, WORD newWord) 


Table A.5 lists functions that encapsulate window placement and display properties. 


Table A.5 


CeiWindow Placement 


Window placement 


GetWindowText int GetWindowText (char far* str, int maxCount) const 
GetWindowTextLength int GetWindowTextLength () const 

IsIconic BOOL IsIconic () const 

IsWindow Visible BOOL IsWindow Visible () const 

IsZoomed BOOL IsZoomed () const 

MoveWindow void MoveWindow (const TRect& rect, BOOL repaint = FALSE) 
MoveWindow void MoveWindow (int x, int y, int w, int h, BOOL repaint = FALSE) 
SetWindowPlacement BOOL SetWindowPlacement (const WINDOWPLACEMENT *place) 
SetWindowText void SetWindowText (const char far* str) 

ShowOwnedPopups void ShowOwnedPopups (BOOL show) 

ShowWindow BOOL Show Window (int cmdShow) 


The functions in Table A.6 control window positions and sibling relationships. 


Table A.6 


Window relationships 


BOOL GetWindowPlacement (WINDOWPLACEMENT *place) const _ 


ee vee ring indow oTop () 
GetActiveWindow static HWND GetActiveWindow () 
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Table A.6 Window relationships (continued) 


GetDesktopWindow static HWND GetDesktopWindow () 
GetLastActivePopup HWND GetLastActivePopup () const 


GetNextWindow HWND GetNextWindow (UINT dirFlag) const 

GetSysModalWindow static HWND GetSysModalWindow () 

GetTopWindow HWND GetTopWindow () const 

SetActiveWindow HWND SetActiveWindow () 

SetSysModalWindow | HWNDSetSysModalWindow () 

SetWindowPos _ void SetWindowPos (HWND hWndiInsertAfter, const TRect& rect, UINT flags) 

SetWindowPos he nee (HWND hWndiInsertAfter, int x, int y, int w, int h, UINT 
ags 


The encapsulated functions in Table A.7 control window pomne, invalidating, 
validating, and updating. 


Table A.7_ ~— Window painting functions 


FlashWindow BOOL FlashWindow (BOOL invert) 

GetUpdateRect BOOL GetUpdateRect (TRect& rect, BOOL erase = rer) const 

Invalidate void Invalidate (BOOL erase = TRUE) 

InvalidateRect void InvalidateRect (const TRect& rect, BOOL erase = TRUE) 

InvalidateRgn void InvalidateRgn (HRGN hRgn, BOOL erase = TRUE) 

LockWindowUpdate = BOOL LockWindowUpdate () 

RedrawWindow BOOL RedrawWindow (TRect *update, HRGN hUpdateRgnh, UINT 
redrawFlags = ROW_INVALIDATE | RDW_UPDATENOW | RDW_ERASE) 

UpdateWindow void UpdateWindow () 

Validate void Validate () _ 

ValidateRect void ValidateRect (const TRect& rect) 

ValidateRgn void ValidateRgn (HRGN hRgn) 


The functions in Table A.8 control window scrolling and scroll bars. 


Table A.8 Window scrolling functions 


-GetScrollPos int GetScrollPos (int bar) 
GetScrollRange void GetScrollRange (int bar, int &minPos, int &maxPos) const 
ScrollWindow void ScrollWindow (int dx, int dy, const TRect *scroll = 0, const TRect *clip = 0) 


ScrollWindowEx — void ScrollWindowEx (int dx, int dy, const TRect *scroll = 0, const TRect *clip = 0, 
HRGN hUpdateRgn = 0, TRect *update = 0, UINT flags = 0) 


SetScrollPos int SetScrollPos (int bar, int pos, BOOL redraw = TRUE) 
SetScrollRange void SetScrollRange (int bar, in minPos, int maxPos, BOOL redraw = TRUE) 
ShowscrollBar = void ShowScrollBar (int bar, BOOL show = TRUE) 
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®. 


The functions in Table A.9 control parent and child windows using command IDs. 


Table A.9 


CheckDgButton 
CheckRadioButton 
GetDlgCtrID 
GetDlgItem 
GetDlgltemInt 
GetDlgitemText 
GetNextDlgGroupItem 


GetNextDlgTabltem 


GetParent 

IsChild 
IsDlgButtonChecked 
SetDlgItemInt 
SetDlgItemText 


a \ ‘Aine’ : oo a Function declaration | 


Child window ID functions 


void CheckDigButton (int buttonld, UINT si 

void CheckRadioButton (int firstButtonId, int lastButtonId, int checkButtonId) 
int GetDlgCtrlID () const 

HWND GetDIigltem (int childId) const 

UINT GetDlgItemInt (int childId, BOOL * translated, BOOL isSigned) const 
int GetDlgItemText (int childId, char far* text, int max) const 


HWND GetNextDlgGroupItem (HWND hWndCtrl, BOOL previous = FALSE) 
const 


HWND GetNextDlgTablItem (HWND hWndCtrl, BOOL previous = FALSE) 
const 


HWND GetParent () const 

BOOL IsChild (HWND) const 

UINT IsDlgButtonChecked (int buttonId) const 

void SetDlgItemInt (int childId, UINT value, BOOL is Signed = TRUE) const 
void SetDlgItemText (int childId, const char far* text) const 


The functions in Table A.10 control menus and menu bar operations. 


Table A. i Salil a0) menu val cL 


i Name > 
cone veer 
GetMenu 
GetSystemMenu 
HiliteMenultem. 
SetMenu 


void DrawMenuBar () 
HMENU GetMenu () 
HMENU GetSystemMenu (BOOL revert = FALSE) 
BOOL HiliteMenultem (HMENU, UINT idItem, UINT hilite) 
BOOL SetMenu (HMENU) 


The functions in Table A.11 controls Clipboard operations. 


Table A.11 


Clipboard mane 


&OpenClipboard _ 


TClipBoard &OpenC pboard ( ) 


The functions in Table A.12 control timer operations. 


Table A.12 Timer functions 


| KillTimer 
SetTimer 


BOOL KillTimer (UINT timerld) 
BOOL SetTimer (UINT timerld, UINT timeout, TIMERPROC proc = 0) 
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The functions in Table A.13 control caret and cursor operations. 


Table A.13  Caret and cursor functions 


reateCare reateCaret (H ) | 
CreateCaret void CreateCaret (int shade, int width, int height) 
DestroyCaret static void DestroyCaret () 
GetCaretBlinkTime static UINT GetCaretBlinkTime () 
GetCaretPos static void GetCaretPos (TPoint& pos) 
GetCursorPos static void GetCursorPos (TPoint& pos) 
HideCaret ~ void HideCaret () 
SetCaretBlinkTime __ static void SetCaretBlinkTime (WORD milliSecs) 
SetCaretPos static void SetCaretPos (const TPoint& pos) | 
SetCaretPos static void SetCaretPos (int x, int y) 


The functions in Table A.14 control the operations of hot keys. 


Table A.14 Hot key functions 


RegisterHotKey BOOL RegisterHotKey (int idHotKey, UINT modifiers, UINT 
virtKey)” 


UnregisterHotKey | BOOL UnregisterHotKey (int idHotKey)! 


1. WIN32 API only 


The functions in Table A.15 control miscellaneous operations such as accessing 
WinHelp. 


Table A.15 Help and task functions 


_DragAcceptFiles = void DragAcceptFiles (BOOL accept) 
GetWindowTask HANDLE GetWindowTask () const! 
GetWindowTask HTASK GetWindowTask () const? 
MessageBox int MessageBox (const char far* text, const char far* caption = 0, UINT type = MB_OK) 
WinHelp BOOL WinHelp (const char far* helpFile, UINT command, DWORD data) 


1. WIN32 API only 
2. WIN16 API only 
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Windows API structs 


This appendix lists several Windows API structs that ObjectWindows uses. 


ABC struct inde 


typedef struct ABC { 
int abcA; 
UINT abcB; 
int abcC; 
} ABC; | 
The ABC structure contains the width of a character in a TrueType” font. 


. MA characher spacing. A" spacing is the distance to add to the current position before _ 
drawing the character glyph. 


abcB "B" character spacing. "B" spacing is the width of the drawn portion of the character glyph. 


abcC "C" character spacing. "C" spacing is the distance to add to the current position to provide 
white space to the right of the character glyph. 


The total width of a character is the sum of abcA, abcB, and abcC. Either the abcA or abcC 
can be negative to indicate underhangs or overhangs. 


16-bit version: 

typedef struct tagBITMAP { 
int bmType; 
int bmWidth; 
int bmHeight; 
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BITMAPCOREHEADER struct 


int bmWidthBytes; 
BYTE bmPlanes; 


BYTE bmBitsPixel; 


void FAR* bmBits; 


} BITMAP; 


32-bit version: 


typedef struct tagBITMAP { 


LONG bmType; 
LONG bmWidth; 
LONG bmHeight; 


LONG bmWidthBytes; 
WORD bmPlanes; 
WORD bmBitsPixel; 


LPVOID bmBits; 


} BITMAP: 


BITMAP defines the height, width, color format, and bit values of a logical bitmap. 


yp 
bmWidth 


bmHeight 
bmWidthBytes 


bmPlanes 
bmBitsPixel 
bmBits 


p type. &} PS, 


_ Bitmap width in pixels. Must be greater than zero. 


Bitmap height in raster lines. Must be greater than zero. 

Number of bytes per raster line. Must be an even number because the graphics device 
interface (GDI) assumes that the bit values of a bitmap form an array of integer (two- 
byte) values. | 

Number of bitmap color planes. 

Number of adjacent color bits on each plane needed to define a pixel. 


Points to the location of the bitmap bit values. Must be a long pointer to an array of one- 
byte values. 


Currently used bitmap formats are monochrome and color. Monochrome bitmaps use a 
one-bit, one-plane format. Each scan is a multiple of 16 bits or 32 bits. A monochrome 
bitmap of height n is organized as follows: 


Scan 0 
Scan 1 


Scan n-2 
Scan n-1l 


Monochrome device pixels are black or white. If a bitmap bit is 1, the corresponding 
pixel is turned on (white). If a bitmap is 0, the corresponding pixel is turned off (black). 


typedef struct BOONE Conetenoe { 


~ DWORD bcSize; 
WORD beWidth; 


WORD bcHeight; © 
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BITMAPCOREINFO struct 


WORD bePlanes; 

WORD bcBitCount; 

} BITMAPCOREHEADER; 

Contains device-independent bitmap (DIB) dimension and color-format information. 


‘Member Description — 

bcSize Number of bytes required oy the structure. 
bceWidth Width of the bitmap, in pixels. 

bcHeight §_ Height of the bitmap, in pixels. 

bcPlanes Number of planes for the target device. Must be 1. 
bcBitCount Number of bits per pixel. Must be 1, 4, 8, or 24. 


This structure is combined with a color table in the BITMAPCOREINFO structure to 
provide a complete definition of the dimensions and colors of a DIB. 


Seealso BITMAPCOREINEO struct, RGBTRIPLE struct 


typedef struct_ BITMAPCOREINFO { 

BITMAPCOREHEADER bmciHeader; 

RGBTRIPLE bmciColors[1]; 
} BITMAPCOREINFO; | 

Defines the dimensions and color information for a device-independent bitmap (DIB). 


bmciHeader seeming Grain DIB color and aaaeinnent pram | 
bmciColors Structure defining bitmap colors. 


A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions 
and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits 
in the array are packed together, but each scan line must be padded with zeroes to end 
on a LONG boundary. The origin of the bitmap is the lower left corner. 


The bcBitCount member of the BITMAPCOREHEADER structure determines the 
number of bits that define each pixel and the maximum number of colors in the bitmap. 
This member can be one of the following values: 


_ The bitmap i is monochrome, and the bmciColors member contains PaO entries. each bitin the — 
bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first 
entry in the bmciColors table; if the bit is set, the pixel has the color of the second entry in the 
table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors member contains up to 16 entries. 
Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the 
first byte in the bitmap is Ox1F, the byte represents two pixels. The first pixel contains the color in 
the second table entry, and the second pixel contains the color in the sixteenth table entry. 
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BITMAPINFO struct 


8 The bitmap has a maximum of 256 colors, and the bmciColors member contains up to 256 entries. 
In this case, each byte in the array represents a single pixel. 
24 The bitmap has a maximum of 2 colors, and the bmciColors member is NULL. Each 3-byte triplet 
in the bitmap array represents the relative intensities of red, green, and blue, respectively, for a 
‘pixel. 


The colors in the bmciColors table should appear in order of importance. 


Alternatively, for functions that use DIBs, the bmciColors member can be an array of 16- 
bit unsigned integers that specify indexes into the currently realized logical palette, 
instead of explicit RGB values. In this case, an application using the bitmap must call the 
DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the 
iUsage parameter set to DIB_PAL_ COLORS. 


Note The bmciColors member should not contain palette indexes if the bitmap is to be stored 
in a file or transferred to another application. Unless the application has exclusive use 
and control of the bitmap, the bitmap color table should contain explicit RGB values. 


16-bit version: 

typedef struct tagBITMAPINFO { 

BITMAPINFOHEADER bmiHeader; 

RGBQUAD bmiColors[1]; 

} BITMAPINFO; 

Defines the dimensions and color i emaaon for a device-independent bitmap (DIB). 


bmiHeader Structure containing DIB dimension and color-format information. 
bmiColors Structures that defines bitmap colors. 


A DIB consists of a BITMAPINFO structure, which describes the dimensions and colors 
of the bitmap, and an array of bytes defining the bitmap pixels. The array bits are 
packed together, but each scan line must be zero-padded to end on a LONG boundary. 
Segment boundaries can appear ee in the bitmap. The bitmap ae is the 
lower-left corner. 
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BITMAPINFOHEADER struct 


The biBitCount member of the BITIMAPINFOHEADER structure determines the number 
of bits which define each pixel and the maximum number of colors in the bitmap. This 
member may be set to any of the following values: 


‘Value Description _ 


1 The bitmap is monochrome, aad ihe bmciColors racinners must contain two entries. Fach n biti in cine 
bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first 
entry in the bmciColors table. If the bit is set, the pixel has the color of the second entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors member contains 16 entries. Each 
pixel in the bitmap is represented by a four-bit index into the color table. For example, if the first 
byte in the bitmap is Ox1F, the byte represents two pixels. The first pixel contains the color in the 
second table entry, and the second pixel contains the color in the sixteenth table entry. 


8 The bitmap has a maximum of 256 colors, and the bmciColors member contains 256 entries. In this 
case, each byte in the array represents a single pixel. 


16 The bitmap has a maximum of 216 colors. The biCompression member of the 
BITMAPINFOHEADER must be BI_BITFIELDS. The bmiColors member contains 3 DWORD 
color masks which specify the red, green, and blue components, respectively, of each pixel. Bits 
set in the DWORD mask must be contiguous and should not overlap the bits of another mask. 
All the bits in the pixel do not have to be used. Each WORD in the array represents a single pixel. 


24 The bitmap has a maximum of 2 colors. The bmciColors member is NULL, and each 3-byte 
sequence in the bitmap array represents the relative intensities of red, green, and blue, 
respectively, of a pixel. 


32 . The bitmap has a maximum of 2 colors. The biCompression member of the 
BITMAPINFOHEADER must be BL_BITFIELDS. The bmiColors member contains 3 DWORD 
color masks which specify the red, green, and blue components, respectively, of each pixel. Bits 
set in the DWORD mask must be contiguous and should not overlap the bits of another mask. 
All the bits in the pixel do not have to be used. Each DWORD in the array represents a i single 
pixel. 


The biClrUsed member of the BITMAPINFOHEADER structure specifies the number of 
color indexes in the color table actually used by the bitmap. If the biClrUsed member is 
set to zero, the bitmap uses the maximum number of colors corresponding to the value 
of the biBitCount member. The colors in the bmiColors table should appear in order of 
importance. 


Alternatively, for functions that use DIBs, the bmiColors member can be an array of 16- 
bit unsigned integers that specify an index into the currently realized logical palette 
instead of explicit RGB values. In this case, an application using the bitmap must call 
DIB functions (CreateD Bitmap, CreateDIBPatternBrush, and CreateDIBSection) with the 
wUsage parameter set to DIB_PAL_ COLORS. 


Note The bmiColors member should not contain palette indexes if the bitmap is to be stored in 
a file or transferred to another application. Unless the application uses the bitmap 
exclusively and under its complete control, the bitmap color table should contain 
explicit RGB values. 


typedef struct tagBITMAPINFOHEADER { 
DWORD biSize: 

LONG biWidth; 

LONG biHeight; 
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BITMAPINFOHEADER struct 


WORD biPlanes; 


WORD biBitCount; 


DWORD biCompression; - 
DWORD biSizelmage; 
LONG bixPelsPerMeter; 
LONG biYPelsPerMeter; 


DWORD biClrUsed; 


DWORD biClrlmportant; 
} BITMAPINFOHEADER; 
Contains dimension and color-format information for device-independent bitmaps 


(DIB). 


‘biSize 
biWidth 
biHeight 


biPlanes 
biBitCount 


biCompression 


biSizelmage 
biXPelsPerMeter 


biYPelsPerMeter 


M q y 
Width of the bitmap, in pixels. 


Height of the bitmap, in pixels. If biHeight is negative, the bitmap origin is the upper- 
left corner and the height is the absolute value of biHeight. 


Specifies the number of planes for the target device. This member must be set to 1. 


Specifies the number of bits per pixel. This value must be 1, 4, 8, 16 (16-bit only), 24, or © 
32 (32-bit only). | 


Specifies the type of compression for a compressed bitmap. It can be one of the 
following values: 


Value Meaning 

BI_RGB Uncompressed. 

BI_RLE8 Specifies a run-length encoded format for bitmaps with 8 bits per 
pixel. 

BI_RLE4 Specifies a run-length encoded format for bitmaps with 4 bits per 
pixel. 


BI_BITFIELDS Specifies the bitmap is not compressed and the color table consists 
of 3 DWORD color masks which specify the red, green, and blue 
components, respectively, of each pixel. This is valid when used 
with 16 and 32 bits per pixel bitmaps. 


Size of the image, in bytes. Can be 0 if the bitmap is in the BI_LRGB format. 


Specifies the horizontal resolution, in pixels per meter, of the target device for the 
bitmap. Use this value to select a bitmap from a resource group that best matches the 
characteristics of the current device. 


Specifies the vertical resolution, in pixels per meter, of the target device. 
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COLORREF typedef 


Member 3 Description | 


biClrUsed Size of the i image, in bytes. Can be 0 if the praapes is in the BI RGB format. 


Specifies the horizontal resolution, in pixels per meter, of the target device for the 
bitmap. Use this value to select a bitmap from a resource group that best matches the 
characteristics of the current device. 


Specifies the vertical resolution, in pixels per meter, of the target device. 


Specifies the number of color indexes in the color table actually used by the bitmap. If 
this value is 0, the bitmap uses the maximum number of colors corresponding to the 
value of the biBitCount member. 


For 16-bit applications, if biClrUsed is nozero, it specifies the actual number of colors 
that the graphics engine or device driver will access if the biBitCount member is less 
than 24. If biBitCount is set to 24, biClrUsed specifies the size of the reference color table 
used to optimize performance of color palettes. 


For 32-bit applications, if biClrUsed is nonzero and the biBitCount member is less than 
16, the biClrUsed member specifies the actual number of colors the graphics engine or 
device driver accesses. If biBitCount is 16 or greater, then biClrUsed member specifies 
the size of the color table used to optimize performance of Windows color palettes. 
For biBitCount equal to 16 or 32 the optimal color Beets starts immediately following 
the 3 DWORD masks. 


If the bitmap is a packed bitmap (that is, a bitmap in which the bitmap array 
immediately follows the BITMAPINFO header and which is referenced by a single 
pointer), the biClrUsed member must be set to zero or to the actual size of the color 
table. 


biClrImportant Specifies the number of color indexes that are considered important for displaying the 
bitmap. If this value is zero, all colors are important. 


COLORREF typedef windows.h 


typedef DWORD COLORREF; 
A 32-bit value used to specify an RGB color. The COLORREF value has the following 
hexadecimal form: 


Ox00bbggrr 


The low-order byte (rrcontains a value for the relative intensity of red; the second byte 
(ggcontains a value for green; and the third byte (bbcontains a value for blue. The fourth 
byte byte must be zero. The RGB macro can be used to set these values: 


RGB(red, green, blue) 


Each color parameter can range from 0x0 to OxFF. 


COMPAREITEMSTRUCT struct _windlows.h 


typedef struct tagCOMPAREITEMSTRUCT { 
UINT CtlType; 

UINT CtlID; 

HWND_ hwndltem; 

UINT itemID1; 

DWORD itemData1; 

UINT itemID2; 
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DELETEITEMSTRUCT struct 


DWORD itemData2; 
} COMPAREITEMSTRUCT; 


Supplies the identifiers and aspletion stippled data for two items in a sorted owner- 
drawn list box or combo box. The table below describes the members. 


CtlType Either ODT_LISTBOX for an owner-drawn list box, or ODT_COMBOBOxX for an owner- 
| drawn combo box. 


CtlID. | List box or combo box identifier. 


hwndltem Control identifier. 

itemID1 Index of the first item in the list box or combo box being compared. 
itemDatal Application-supplied data for the first item being compared. | 
itemID2 Index of the second item in the list box or combo box being compared. 
itemData2 Application-supplied data for the second item being compared. 


typedef struct tagDELETEITEMSTRUCT { 

UINT CtlType; 

UINT CtlID; 

UINT itemID; 

HWND hwndltem; 

UINT itemData; 
} DELETEITEMSTRUCT; | 
Describes a deleted owner-drawn list-box or combo-box item. The table below describes 
the members. 


CtlType Either ODT_LISTBOX for an owner-drawn list box, or ODT_ COMBOBOX for an owner- 


drawn combo box. 
CtlID List box or combo box identifier. 
itemID Index of the item in the list box or combo box being removed. 


hwndlItem Control indentifier. 
itemData Application-defined item data. 


16-bit version: 

typedef struct tagDEVMODE { 

char dmDeviceName[CCHDEVICENAME];: 
UINT dmSpecVersion; 

UINT dmDriverVersion; 

UINT dmSize; 

UINT dmDriverExtra; 

DWORD dnFields; 


1 
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int dmOrientation; 
int dmPaperSize; 
int dmPaperLength; 
int dmPaperWidth; 
int dmScale; 

int dmCopies; 

int dmDefaultSource; 
int dmPrintQuality; 
int dmColor; 

int dmDuplex; 

int dmYResolution; 
int dmTTOption; 

} DEVMODE; 


32-bit version: 

typedef struct _devicemode { 
TCHAR dmDeviceName[32]; 
WORD dmSpecVersion; 
WORD dmDriverVersion; 
WORD dmSize; 

WORD dmDriverExtra; 
DWORD dnFields; 

short dmOrientation; 

short dmPaperSize; 

short dmPaperLength; 
short dmPaperWidth; 

short dmScale; 

short dmCopies; 

short dmDefaultSource; 
short dmPrintQuality; 

short dmColor; 

short dmDuplex; 

short dmYResolution; 

short dmTTOption; 

short dmCollate; 

TCHAR dmFormName[32]; 
WORD dmUnusedPadding; 
USHORT dmBitsPerPel; 
DWORD dmPelsWidth; 
DWORD dmPelsHeight; 
DWORD dmDisplayFlags; 
DWORD dmDisplayFrequency; 
} DEVMODE; 


DEVMODE struct 
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DEVMODE struct | 


Contains printer-driver initialization and environment data. The following table 
describes each member. | 


dmDeviceName Name of the device the driver ep pores o example, PCL/ Laserjet: in the case 
of the Hewlett-Packard Laserjet. 
dmSpecVersion _ Version number of this structure. . 
dmDriverVersion Printer driver version number. 
dmSize Size of this structure, in bytes,excluding dmDriverData. Use to find the length of 
3 the structure without having to account for different versions. 
dmDriverExtra Size of the optional dmDriverData member, in bytes. If an application does not use 
device-specific information, it should set this member to zero. | 
-dmFields Contains flags that indicate which of the remaining members in this structure 
have been initialized. It can be any combination of the following values: 
DM_ORIENTATION DM_DEFAULTSOURCE 
DM_PAPERSIZE DM_PRINTQUALITY 
DM_PAPERLENGTH DM_COLOR 
DM_PAPERWIDTH DM_DUPLEX 
DM_SCALE DM_YRESOLUTION 
DM_COPIES DM_TTOPTION 
dmOrientation Paper orientation. Can be DMORIENT_PORTRAIT or 
DMORIENT_LANDSCAPE. 
dmPaperSize Paper size. Can be set to zero if the length and width of the paper are specified by 
dmPaperLength and dmPaperWidth. Otherwise, set to one of the following values: 
Value Meaning 
DMPAPER_FIRST ~  _DMPAPER_ LETTER 
DMPAPER_ LETTER Letter,81/2x 11 in. 
DMPAPER_LETTERSMALL Letter Small, 8 1/2x 11 in. 
DMPAPER_TABLOID Tabloid, 11 x 17 in. 
DMPAPER_LEDGER Ledger, 17 x 11 in. 
DMPAPER_LEGAL Legal, 81/2 x 14 in. 
DMPAPER STATEMENT Statement, 51/2 x 81/2 in. 
DMPAPER_ EXECUTIVE Executive, 71/2 x 10 1/2 in. 
DMPAPER_A3 ~ A3, 297 x 420 mm 
DMPAPER_A4 A4, 210 x 297 mm 
DMPAPER_A4SMALL A4 Small, 210 x 297 mm 
DMPAPER_A5 A5, 148 x 210 mm 
~ DMPAPER_B4 B4, 250 x 354 mm 
DMPAPER_B5 B5, 182 x 257 mm 
DMPAPER_FOLIO | Folio, 81/2 x 13 in. 
DMPAPER_QUARTO | | Quarto, 215 x 275 mm 
DMPAPER_ 10X14. | 10 x 14 in. 
DMPAPER_11X17 11x 17 in. 
DMPAPER_NOTE Note, 81/2 x 11 in. 
DMPAPER_ENV_9 Envelope #9,3 7/8 x 87/8 in. 
DMPAPER_ ENV_10 Envelope #10, 41/8 x9 1/2 in. 
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DEVMODE struct 


Description ee 
DMPAPER ENV_11 Envelope #11, 41/2 x 10 3/8 in. 
DMPAPER_ENV_12 Envelope #12, 41/2 x 11 in. 
DMPAPER_ENV_14 Envelope #14, 5 x 11 1/2 in. 
DMPAPER_CSHEET C size sheet 

DMPAPER_ DSHEET D size sheet 
DMPAPER_ESHEET E size sheet 

DMPAPER ENV_DL Envelope DL, 110 x 220 mm 
DMPAPER_ ENV_C3 Envelope C3, 324 x 458 mm 
DMPAPER_ENV_C4 Envelope C4, 229 x 324 mm 
DMPAPER_ENV_C5 Envelope C5, 162 x 229 mm 
DMPAPER_ ENV_C6 Envelope C6, 114 x 162 mm 
DMPAPER_ENV_C65 Envelope C65, 114 x 229 mm 
DMPAPER_ENV_B4 Envelope B4, 250 x 353 mm 
DMPAPER_ENV_B5 Envelope B5, 176 x 250 mm 
DMPAPER_ENV_B6 Envelope B6, 176 x 125 mm 
DMPAPER_ENV_ITALY Envelope, 110 x 230 mm 


DMPAPER_ENV_MONARCH © Envelope Monarch, 37/8 x 7 1/2 in. 
DMPAPER_ENV_PERSONAL — Envelope,35/8 x 6 1/2 in. 
DMPAPER_FANFOLD_US U.S. Standard Fanfold, 14 7/8 x 11 in. 
DMPAPER_FANFOLD STD_ German Standard Fanfold, 8 1/2 x 12 in. 


GERMAN 
DMPAPER_FANFOLD_LGL_ German Legal Fanfold, 8 1/2 x 13 in. 
GERMAN — 
DMPAPER LAST German Legal Fanfold, 8 1/2 x 13 in. 
DMPAPER USER User-defined 

dmPaperLength Paper length, in tenths of a millimeter. Overrides dmPaperSize. 

dmPaperWidth Paper width, in tenths of a millimeter. Overrides dmPaperSize. 

dmScale Print output scale factor. Apparent page size is scaled from the physical page size 
by dmScale/100. 

dmCopies Specifies the number of copies printed if the device supports multiple-page 
copies. 

dmDefaultSource Default paper feed bin. This member can be one of the following values: 
DMBIN_AUTO DMBIN_LOWER 
DMBIN_CASSETTE DMBIN_MANUAL 
DMBIN_ENVELOPE DMBIN_MIDDLE 
DMBIN_ENVMANUAL DMBIN_ONLYONE 
DMBIN_FIRST DMBIN_SMALLFMT 
DMBIN_LARGECAPACITY DMBIN_TRACTOR 
DMBIN_LARGEFMT DMBIN_UPPER 
DMBIN_LAST 

mPrintQuality Printer resolution. Can be one of the following values: 
DMRES_HIGH 
DMRES_MEDIUM 
DMRES_LOW 
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DRAWITEMSTRUCT struct 


dmColor 


dmDuplex 


dmYkResolution 


dmTTOption 


dmUnusedPadding 
dmCollate 


dmFormName 
dmBitsPerPel 
dmPelsWidth 
dmPelsHeight 
dmDisplayFlags 


dmDisplayFrequency 


~ DRAWITEMSTRUCT struct 


DMRES_DRAFT 


If another (positive) value is given, it specifies dots per inch (DPI) and is device- 
dependent. If the printer initializes dmY Resolution, then dmPrintQuality specifies 
the x-resolution of the printer in DPI. 


Color or monochrome output. Can be DMCOLOR_COLOR, or 
DMCOLOR_MONOCHROME. 


Duplex (double-sided) printing for printers capable of duplex printing. This 


- member can be one of the following values: 


DMDUP_SIMPLEX 
DMDUP_HORIZONTAL 
DMDUP_VERTICAL 


Y-resolution of the printer in DPI. If the printer initializes dmY Resolution, 
dmPrintQuality specifies the x-resolution of the printer, in DPI. 


TrueType-font printing. Can be one of the following values: 
Value | 
DMTT_BITMAP 


Meaning 
Print TrueType fonts as graphics. The default 
for dot-matrix printers. 


Download TrueType fonts as soft fonts. 
Default for Hewlett-Packard printers that use 
Printer Control Language (PCL).. 


DMTT_DOWNLOAD 


DMTT_SUBDEV Substitute device fonts for TrueType fonts. 


Default for PostScript printers. 
(32-bit only) Used to align the structure ona DWORD boundary. 
Collation when printing multiple copies. Can be be one of the following values: 
DMCOLLATE_TRUE | 
DMCOLLATE_FALSE 


Collate when printing multiple copies. 


Do NOT collate when printing multiple 
copies. | 


(32-bit only) Specifies the name of the form to use; for example, "Letter" or "Legal". 
(32-bit only) Color resolution of the display device, in bits per pixel. 

(32-bit only) Width of the visible device surface, in pixels. 

(32-bit only) Height of the visible device surface, in pixels. 

(32-bit only) Device display mode. Can be one of the following values: 

Value 
DM_GRAYSCALE 


Meaning 


Non-color display. If this flag is not set, color is 
assumed. | 


DM_INTERLACED Interlaced display mode. If the flag is not set, 


non-interlaced is assumed. 
(32-bit only) Specifies the display device frequency, in hertz. 


windows.h 


typedef struct tagDRAWITEMSTRUCT { 


UINT CtlType; 
UINT CtlID; 
UINT itemID; 
UINT itemAction; 
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DRAWITEMSTRUCT struct 


UINT itemState; 
HWND hwndltem; 


HDC hDC; 


RECT rcltem: 


DWORD itemData; 
} DRAWITEMSTRUCT; 
Provides information the owner window must have to determine how to paint an 
owner-drawn control or menu item. The owner window of the owner-drawn control or 
menu item receives a pointer to this structure as the /Param parameter of the 
WM_DRAWITEM message. 


Member 
CtlType 


CtlID 


itemID 


itemAction 


itemState 


hwndItem 


hDC 


Description | eee 

Specifies the control type. This member can be one of the following values: 
ODT_BUTTON Owner-drawn button 

ODT_COMBOBOX Owner-drawn combo box 

ODT_LISTBOX Owner-drawn list box 

ODT_MENU Owner-drawn menu item 


Specifies the identifier of the combo box, list box, or button. This member is not used for a 
menu item. 


Specifies the menu item identifier for a menu item or the index of the item in a list box or 
combo box. For an empty list box or combo box, this member can be -1. This allows the 
application to draw only the focus rectangle at the coordinates specified by the rcltem 
member even though there are no items in the control. This indicates to the user whether the 
list box or combo box has the focus. How the bits are set in the itemAction member 
determines whether the rectangle is to be drawn as though the list box or combo box has the 
focus. | 


Specifies the drawing action required. This member can be one or more of the following 
values: 


Value Meaning 

ODA_DRAWENTIRE The entire control needs to be drawn. 

ODA_FOCUS The control has lost or gained the keyboard focus. The itemState 
member should be checked to determine whether the control 
has the focus. 

ODA_SELECT The selection status has changed. The itemState member should 


be checked to determine the new selection state. 


Specifies the visual state of the item after the current drawing action takes place. This 
member can be a combination of the following values: 


Value Meaning 

ODS_CHECKED The menu item is to be checked. This bit is used only in a menu. 
ODS_DISABLED The item is to be drawn as disabled. 

ODS_FOCUS The item has the keyboard focus. 

ODS_GRAYED The item is to be grayed. This bit is used only in a menu. 
ODS_SELECTED The menu item's status is selected. 


Identifies the control for combo boxes, list boxes, and buttons. For menus, this member | 
identifies the menu containing the item. 


Identifies a device context (DC); this DC must be used when performing drawing operations 
on the control. 
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FINDREPLACE struct 


Specifies z a rectangle that defines the boundaries of the control to be drawn. This rectangle i is 
in the DC specified by the hDC member. Anything the owner window draws in the DC for 
combo boxes, list boxes, and buttons is automatically clipped, except for menu items. When 
drawing menu items, the owner window must not draw outside the boundaries of the 
rectangle defined by the rcltem member. 


itemData Specifies the application-defined 32-bit value associated with the menu item. For a control, 
this parameter specifies the value last assigned to the list box or combo box by the 
LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the 
LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is initially zero. Otherwise, this 
value is initially the value that was passed to the list box or combo box in the [Param 
parameter of one of these messages: CB_ADDSTRING, CB_INSERTSTRING, 
LB_ADDSTRING, LB_INSERTSTRING. 


typedef struct { 

DWORD IStructSize; 

HWND hwndOwner; 

HINSTANCE _hinstance; 

DWORD Flags; 

LPSTR IpstrFindWhat; 

LPSTR lpstrReplaceWith; 

WORD wFindWhatLen; 

WORD wReplaceWithLen; 

DWORD ICustData; 

LPFRHOOKPROC IpfnHook; 

LPCSTR lp TemplateName; 

} FINDREPLACE; 

Contains initialization information to initialize the system-defined find-and-replace 
dialog boxes. The table below describes the members. 


IStructSize Length, in bytes, of the structure. 
hwndOwner Window that owns the dialog box. Can be any valid window handle, but must not 
be NULL. 
hInstance Data block that contains a dialog box template specified by [pstrTemplateName. 
Used only if the Flags member is set to FR _ENABLETEMPLATE; otherwise 
ignored. 
Flags Dialog box initialization flags. Can be a combination of the following values: 
Value Meaning 
FR_DIALOGTERM | Indicates that the dialog box is closing. 
FR_DOWN If this flag is set, the search direction is 
down, if the flag is clear, the search direction 
is up. 
FR_ENABLEHOOK Enables the hook function specified in the 


lpfnHook member of this structure. Used to. 
initialize the dialog box only. 
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FINDREPLACE struct 


Member ; = Description 


FR _ENABLETEMPLATE ee the ialog oe byt using the ee 
box template identified by the Instance and 
lpTemplateName members. This flag is used 
to initialize the dialog box only. 


FR_ENABLETEMPLATEHANDLE _ Indicates that the hInstance member 
identifies a data block that contains a 
preloaded dialog box template. The 
lpTemplateName member is ignored if this 


flag is specified. 

FR_FINDNEXT The application should search for the next 
occurrence of the string specified by the 
lpstrFindWhat member. 

FR_HIDEUPDOWN Hides the Direction check box and the Up 
and Down controls. 

FR_HIDEMATCHCASE Hides the Match Case check box. 

FR_HIDEWHOLEWORD tt the Match Whole Word Only check 

Ox. 

FR_MATCHCASE Case-sensitive searches. 

FR _NOMATCHCASE Disables the Match Case check box. 

FR_NOUPDOWN Disables the direction radio buttons. 

FR_NOWHOLEWORD Disables the Whole Word check box. 

FR_REPLACE Replace the current occurrence of the string 


specified by lpstrFindWhat with the string 
specified by IpstrReplaceWith. 


FR_REPLACEALL Replace all occurrences of the string 
specified by lpstrFindWhat member with the 
string specified by IpstrReplaceWith. 


FR_SHOWHELP Show the Help button. The hwndOwner 
member must not be NULL if this option is 
specified. 

FR_WHOLEWORD Checks the Whole Word check box. Only 

: whole words matching the search string 
will be considered. 


lpstrFindWhat String to search for. If there is a string specified when the dialog box starts, the 
dialog box initializes the Find What: text control with this string. If the 
FR_FINDNEXT flag is set when the dialog box is opened, the application should 
search for an occurrence of this string by using the FR_DOWN, 
FR_WHOLEWORD, and FR_MATCHCASE flags to further define the direction 
and type of search. The application must allocate a buffer for the string, which 
should be at least 80 characters long. 


IpstrReplaceWith Replacement string for replace operations. 


wFindWhatLen Length, in bytes, of the buffer pointed to by [pstrFindWhat. 

wReplaceWithLen Length, in bytes, of the buffer pointed to by lpstrReplaceWith. 

ICustData Application-defined data the passed to the hook function identified /pfnHook. 
IpfnHeok Points to a hook function that processes messages intended for the dialog box. An 


application must specify the FR_LENABLEHOOK flag in the Flags member to enable 
the function; otherwise, the system ignores this structure member. Should return 
FALSE to pass a message on to the standard dialog procedure, or TRUE to discard 
the message. 


IpstrTemplateName Points to a null-terminated string that names the dialog box template resource to be 
substituted for the standard dialog box template. 
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GLYPHMETRICS struct | : | ee | 


typedef struct GLYPHMETRICS { 
UINT gmBlackBoxx; 
UINT gmBlackBoxY; 
~ POINT gmptGlyphOrigin; 
short gmCellincx; . 
short gmCellincY; 
} GLYPHMETRICS; | | 
Contains information about the Siacement and orientation of a glyph in a character cell, 
specified in logical units. 


gmBlackBoxX Width of the smallest rectangle that completely encloses the glyph. 
gmBlackBoxY Height of the smallest rectangle that completely encloses the glyph. 


gmptGlyphOrigin The x- and y-coordinates of the upper left corner of the smallest rectangle that 
completely encloses the glyph. 


emCellIncX The horizontal distance from the origin of the current character cell to the origin of 
the next character cell. 

gmCellincY The vertical distance from the origin of the current character cell to the origin of the 
next character cell. 


typedef struct tagHANDLETABLE { 
HGDIOBJ objectHandle|1}: 
~ } HANDLETABLE: 
An array of handles that identify a graphics device interface (GDI) object. 


ICONINFO struct, windows 


typedef struct ICONINFO { 
BOOL _ flcon; 
DWORD_ xHotspot; 
DWORD  yHotspot; 
HBITMAP hbmMask; 
HBITMAP hbmColor; 
} ICONINFO: 
The ICONINEFO structure contains information about an icon or a cursor. The following | 
table describes the members. 


fIcon . Set to TRUE if this specifies an icon; FALSE if it specifies a cursor. 


xHotspot Specifies the x-coordinate of a cursor's shot spot. For icons the hot spot is always in the center, 
so this member is ignored. 
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KERNINGPAIR struct 


yHotspot Specifies the y-coordinate of the cursor's hot spot. For icons the hot spot is always in the 
center, so this member is ignored. 

hbmMask _ Specifies the icon bitmask bitmap. For black and white icons the upper half of hbmMask is the 

icon AND bitmask, the lower half is the icon XOR bitmask, and the height should be an even 

multiple of two. For color icons this mask defines the AND bitmask of the icon only. 


hbmColor _ Identifies the icon color bitmap. This member can be optional if this structure defines a black 
and white icon. After the AND bitmask of hbmMask is applied to the destination, the color 
bitmap is applied (using XOR) to the destination. 


typedef struct tagKERNINGPAIR { 
WORD wFirst; 
WORD wsecond; 
int iKernAmount; 
} KERNINGPAIR; 
Defines a kerning pair. The following table describes the members. 


‘wEirst "Character code for the first character in the kerning pair. 
wsecond Character code for the second character in the kerning pair. 
ikernAmount Amount this pair will be kerned if they appear side by side in the same font and size. This 


value is usually negative, and is given in logical units (depending on mapping mode). 


typedef struct tagLOGBRUSH { 
UINT IbStyle; 
COLORREF IbColor; 
int IbHatch; 
} LOGBRUSH; 
Defines the style, color, and pattern of a physical brush. The following table describes 
the members: 


IbStyle Specifies the brush style. This member can be one of the following values: 


Value Meaning 
BS_DIBPATTERN Pattern brush defined by a device-independent bitmap (DIB) 
specification. 


BS_DIBPATTERNPT _ A pattern brush defined by a device-independent bitmap (DIB) 
specification (32-bit only). 


BS_HATCHED Hatched brush. 
BS_ HOLLOW Hollow brush. 
BS_PATTERN Pattern brush defined by a memory bitmap. 
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LOGFONT struct 


BS_NULL Equivalent to Bs_HOLLOW. 
BS_SOLID Solid brush. 


IbColor Specifies the color to draw the brush. If the /bStyle member is the BS_HOLLOW or 
BS_PATTERN value, [bColor is ignored. 


If IpStyle is the BS_DIBPATTERN or BS_DIBPATTERNPT value, the low-order wees of 
IbColor specifies whether the bmiColors members of the BITMAPINFO structure contain 
explicit RGB values or indexes into the currently realized logical palette. The /bColor member 
must be one of the following values: 


Value Meaning 
DIB_PAL_ COLORS Color table consists of an array of 16-bit indexes into the currently 
realized logical palette. 


DIB_RGB_ COLORS — Color table contains literal RGB values. 


IbHatch Specifies a hatch style. The meaning depends on the brush style. If the /bStyle member is the 
BS_DIBPATTERN style, the [bHatch member contains a handle to a packed DIB. If the [bStyle 
member is the BS_DIBPATTERNPT style, the [bHatch member contains a pointer to a packed 
DIB. 


If the IbStyle member is the BS_HATCHED style, the bHatch member specifies the orientation 
of the lines used to create the hatch. This member can be one of the following values: 


Value Meaning 
HS_BDIAGONAL _ 45-degree upward hatch (left to right) 
HS_CROSS | Horizontal and vertical cross-hatch 


HS_DIAGCROSS 45-degree cross-hatch 
HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS_ HORIZONTAL Horizontal hatch 

-HS_VERTICAL —_=Verrtical hatch 


If the [bStylemember is the BS_PATTERN style, [bHatch must be a handle to the bitmap that 
defines the pattern. If the JbStyle member is the BS_SOLID or the BS_HOLLOW style, [bHatch 
is ignored. 


See also BITMAPINEO struct 


LOGFONT struct indo. 


typedef struct tagLOGFONT { 
int lfHeight; 

int lfWidth; 

int lfEscapement; 

int lfOrientation; 

int [fWeight; 

BYTE Ifltalic; 

BYTE (fUnderline; 
BYTE lfStrikeOut; 
BYTE (fCharSet; 

BYTE lfOutPrecision; 
BYTE IfClipPrecision; 
BYTE lfQuality; 

BYTE IfPitchAndFamily; 
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BYTE IfFaceName[LF_FACESIZE]; 
} LOGFONT; 


32 bit version: 
typedef struct tagLOGFONT { /* If */ 
LONG IfHeight; 

LONG IfWidth; 

LONG IfEscapement; 

LONG IfOrientation; 

LONG IfWeight; 

BYTE Ifltalic; 

BYTE IfUnderline; 

BYTE lfStrikeOut; 

BYTE lfCharSet; 

BYTE l|fOutPrecision; 

BYTE IfClipPrecision; 

BYTE lfQuality; 

BYTE IfPitchAndFamily; 

CHAR IfFaceName[LF_FACESIZE]; 
} LOGFONT; 


LOGFONT struct 


Defines font attributes. When creating a logical font, applications can use the default 
settings for most of the members. Unless /fHeight and IfFaceName are given specific 
values, the created logical font will be device dependent. The following table describes 


the members. 


lfHeight (16-bit applications) Font height, in logical units. If greater than zero, it specifies the - 
font cell height. If less than zero, it specifies the character height of the font 


lfWidth 


IfEscapement 
lfOrientation 
lfWeight 


(applications that specify font height in points typically use a negative number for this 
member). If 0, the font mapper uses a default height. The font mapper chooses the 
largest physical font not exceeding the requested size,or the smallest font if the fonts 
exceed the requested size. The absolute value of the /fHeight member must not exceed 
16,384 after it is converted to device units. 

(32-bit applictions) Font height, in logical units. The font height can be specified in one 
of three ways. If [fHeight is greater than zero, it is transformed into device units and 
matched against the cell height of the available fonts. If it is zero, a reasonable default 
size is used. If it is less than zero, it is transformed into device units and the absolute 
value is matched against the character height of the available fonts. For all height 
comparisons, the font mapper looks for the largest font that does not exceed the 
requested size; if there is no such font, it looks for the smallest font available. This 
mapping occurs when the font is used for the first time. 

Average font character width, in logical units, of font characters in logical units. If 0, 
the font mapper chooses a default width. 


Angle between the base line of a character and the x-axis, in tenths of degrees. 
Angle of character base line, tenths of degrees and relative to the bottom of the page. 
Font weight. Can be one of the following values: : 
FW_DONTCARE FW_SEMIBOLD 

FW_THIN FW_DEMIBOLD 

FW_EXTRALIGHT FW_BOLD 

FW_ULTRALIGHT FW_BOLD 

FW_LIGHT FW_ULTRABOLD 
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LOGFONT struct 


FW_NORMAL FW_BLACK 
FW_REGULAR FW_HEAVY 
FW_MEDIUM | 

If the value is 0, a default weight is used. 

Ifltalic Italic font if TRUE. 

lfUnderline Underlined font if TRUE. 

IfStrikeOut Strikeout font if TRUE. 

IfCharSet Font character set. Can be one of the following values: 
ANSI_CHARSET 

DEFAULT_CHARSET (16 bit) 
SYMBOL_CHARSET 

SHIFTJIS_CHARSET (16 bit) 

OEM_CHARSET 

UNICODE_CHARSET (32 bit) 


lfOutPrecision __— Desired output precision. Specifies how closely the output must match the height, 
width, character orientation, escapement, and pitch of the requested font. Can be one 
of the following values: 
_ OUT_CHARACTER,_PRECIS = OUT_STRING_PRECIS 
OUT_DEFAULT_PRECIS OUT_STROKE_PRECIS 
OUT_DEVICE_PRECIS OUT_TT_PRECIS 
OUT_RASTER_PRECIS OUT_TT_ONLY_PRECIS 


lfClipPrecision Desired clipping precision. Specifies how to clip characters partially outside the 
clipping region. Can be any one of the following values: 


CLIP_CHARACTER_ PRECIS CLIP_MASK 
CLIP_DEFAULT_PRECIS CLIP_STROKE_PRECIS 
CLIP_EMBEDDED CLIP_TT_ALWAYS 
CLIP_LH_ANGLES 


To use an embedded read-only font, applications must specify the CLIP_EMBEDDED 
value. 


To achieve consistent rotation of device, TrueType, and vector fonts, an application 

can use the OR operator to combine the CLIP_LH_ANGLES value with any of the 

other /fClipPrecision values. If the CLIP_LH_ANGLES bit is set, the rotation for all 

fonts is dependent on whether the orientation of the coordinate system is left-handed 

or right-handed. If CLIP_LH_ANGLES is not set, device fonts always rotate counter- 
clockwise, but the rotation of other fonts is dependent on the orientation of the 

coordinate system. (For more information about the orientation of coordinate systems, — 

see the description of the [fEscapement member.) | 


lfQuality - Output font quality. Can be one of the following values: 
Value _ Meaning , 
DEFAULT_QUALITY Font appearance does not matter. 
DRAFT_QUALITY | Font appearance is less important than when the 
PROOF QUALITY value is used. | 
PROOF_QUALITY Font character quality is more important than 


matching logical-font attributes. 


\fPitchAndFamily Font family and pitch. The two low-order bits specify the font pitch and can be one of 
the following values: 


DEFAULT_PITCH 
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LOGPALETTE struct 


Member _ Description 
_ _ FIXED_PITCH 

VARIABLE PITCH | 

The four high-order bits of the member specify the font family and can be one of the 


following values: 

Value Meaning 

FF_DECORATIVE | Novelty fonts. 

FF_DONTCARE Don't care or don't know. 

FF_ MODERN Fonts with constant stroke width, with or without 
serifs (e.g. Pica and Courier). 

FF_ ROMAN Fonts with variable stroke width and with serifs 
(e.g. Times New Roman). 

FF_SCRIPT Fonts designed to look like handwriting (e.g. Script 
and Cursive). 

FF_ SWISS Fonts with variable stroke width and without serifs 


| (e.g. Sans Serif). 
Use the Boolean OR operator to match a pitch constant with a family constant. 


lIfFaceName Specifies the typeface name of the font. The length of this string must not exceed 
LF_FACESIZE — 1. 


typedef struct tagLOGPALETTE { 

WORD palVersion; 

WORD palNumEntries; 

PALETTEENTRY palPalEntry[1]; 
} LOGPALETTE; 
Defines a logical color palette. Colors in the palette-entry table should appear in order of 
importance because entries earlier in the logical palette are more likely to be placed in 
the system palette. The following table describes the members: 


"palVersion ce 
palNumEntries Specifies the number of entries in the logical color palette. 


palPalEntry Specifies an array of PALETTEENTRY structures that define the color and usage of each 
entry in the logical palette. 


LOGPEN struct Windows 


typedef struct tagLOGPEN { 
UINT lopnStyle; 
POINT lopnWidth; 
COLORREF lopnColor; 
} LOGPEN; 
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MDICREATESTRUCT struct 


Defines the style, width, and color of a pen. 


lopnStyle Specifies the pen type. This member can be one of the following values: 


Value 3 Meaning 

PS_SOLID Solid pen 

PS_DASH Dashed pen (pen width = 1) 

PS_DOT Dotted pen (pen width = 1) 

PS_DASHDOT Alternating dashes and dots (pen width = 1) 
PS_DASHDOTDOT Alternating dashes and double dots (pen width = 1) 
PS_NULL Invisible pen 


PS_INSIDEFRAME _ Creates a pen that draws a line inside the frame of closed shapes 
produced by graphics device interface (GDI) output functions that 
specify a bounding rectangle. When this style is used with GDI 
output functions. 


lopnWidth Specifies the pen width, in logical units. If the lopnWidth member is zero, the pen is one pixel 
wide on raster devices regardless of the current mapping mode. 


lopnColor Specifies the pen color. 


MDICREATESTRUCT struct 


typedef struct tagMDICREATESTRUCT { 
LPCSTR _ szClass; 
LPCSTR - szTitle; 


HANDLE hOwner; 

int x; 

int = y; 

int cx; 

int cy; 

DWORD _ style; 
LPARAM |Param; 

} MDICREATESTRUCT; 


Contains class, title, location, owner, and size of a Multiple Document Interface (MDI) 
child window. The table below describes the members. 


sZClass Points to a null-terminated string specifying the registered MDI child window name. 


szTitle Points to a null-terminated string specifying the registered MDI child window title. 

hOwner Instance handle for the application creating the MDI child window. 

x Initial position of the left side of the MDI child window. If set to CW_USEDEFAULT, the 
MDI child window is assigned a horizontal position. 

y Initial position of the MDI child window top edge. If set to CW_USEDEFAULT, the MDI 
child window is assigned a default vertical position. _ 

cx Initial width of the MDI child window. If set to CW_USEDEFAULT, the MDI child window 
is assigned a default width. 

cy Initial height of the MDI child window. If set to CW_USEDEFAULT, the MDI child window 


is assigned a default height. 
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METARECORD struct 


‘Member | ‘Description ss 


style Specifies additional ee lon the MDI chile Window. If the MDI client windows was eeated: 
with the MDIS_ALLCHILDSTYLES window style, this member can be any combination of 
the window styles and creation attributes, including those listed in the following table: 


Value Meaning 
WS_MINIMIZE — Created in a minimized state. 
WS MAXIMIZE — Created in a maximized state. 
| WS_HSCROLL — Created with a horizontal scroll bar. 
WS_VSCROLL Created with a vertical scroll bar. 
{Param An application-defined 32-bit value. 


typedef struct tagMETARECORD { 

DWORD rdSize; 

WORD rdFunction; 

WORD rdParm[1]; 

} METARECORD; 

Contains a metafile record. The table below describes the members. 


a Membe Jes 
rdSize —_-Size of the record, in words. 
rdFunction Function number. 
rdParm Function parameters in reverse of the order they are passed to the function. 


typedef struct tag MEASUREITEMSTRUCT { 

UINT CtlType; 

UINT CtlID; 

UINT itemlD; 

UINT itemWidth; 

UINT itemHeight; 

DWORD itemData; 
} MEASUREITEMSTRUCT; | 

Contains dimensions of an owner-drawn control. The table below describes the 
members. 


CtlType Specifies t the control lee and can be one of the following values: 


ODT_BUTTON Owner-drawn button 
ODT_COMBOBOX Owner-drawn combo box 
ODT_LISTBOX Owner-drawn list box 


ODT_MENU Owner-drawn menu 
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MSG struct 


CtlID Identifier of the combo box, list box, or button (not used for menus). 


itemID Menu item identifier for a menu item, or the list box item identifier for a variable-height list 
or combo box (not used for a fixed-height list box, combo box, or for a button). . 


itemWidth Width of a menu item, in pixels. 
itemHeight Height of an individual item ina list box or a menu, in pixels. 


itemData Application-defined 32-bit value associated with a menu item. For a control, this parameter 
specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or 
CB_SETITEMDATA message. If the list box or combo box has the LB_HASSTRINGS or 
CB_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the 
value passed to the list box or combo box in the [Param parameter of one of the following 
messages: 


CB_ADDSTRING 
CB_INSERTSTRING 
LB_ADDSTRING 
LB_INSERTSTRING 


typedef struct tagMSG { 
HWND hwnd; 
UINT message; 

~WPARAM wParam; 
LPARAM |Param; 
DWORD time; 
POINT pt; 

} MSG; 

_ The MSG structure contains the following message information from a message queue: 


wn andle for the window whose window procedure receives the message. 
message § Message number. | 
wParam Additional message information. The meaning depends on the value of message. 
lParam Additional message information. The meaning depends on the value of message. 
time The time the message was posted. 
/ pt The cursor position when the message was posted, in screen coordinates. 


OUTLINETEXTMETRIC struct aindousl. 


typedef struct OUTLINETEXTMETRIC { 
UINT otmSize; 

TEXTMETRIC otmTextMetrics; 

BYTE otmFiller; 

PANOSE otmPanoseNumber; 

UINT otmfsSelection; 
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OUTLINETEXTMETRIC struct 


UINT otmfsType; 

int otmsCharSlopeRise; 

int otmsCharSlopeRun; 

int otmitalicAngle; 

UINT otmEMSquare; 

int otmAscent; 

int otmDescent; 

UINT otmLineGap; 

UINT otmsCapEmHeight; 
UINT otmsXHeight; 

RECT otmrcFontBox; 

int otmMacAscent; 

int otmMacDescent; 

UINT otmMacLineGap; 

UINT otmusMinimumPPEM; 
POINT otmptSubscriptSize; 
POINT otmptSubscriptOffset; 
POINT otmptSuperscriptSize; 
POINT otmptSuperscriptOffset; 
UINT otmsStrikeoutSize; 

int otmsStrikeoutPosition; 
int otmsUnderscoreSize; 
int otmsUnderscorePosition; 
PSTR otmpFamilyName; 
PSTR otmpFaceName; 
PSTR_ otmpStyleName; 
PSTR otmpFullName; 

} OUTLINETEXTMETRIC; 
Contains metrics describing a TrueType font. The sizes returned in are given in logical 
units (depending on the specified display context's current mapping mode). The 
following table describes the members. 


otmSize 


Size of this structure, in bytes 
otmTextMetrics TEXTMETRIC structure containing additional font information 
otmFiller Value that causes this structure to be byte aligned 
otmPanoseNumber The PANOSE number for this font 
otmfsSelection Nature of the font pattern. Can be a combination of the following bits: 
Bit Meaning | 
0 Italic 
1 Underscore 
2 Negative 
3 Outline 
4 Strikeout 
5 Bold 
otmfsType Specifies whether the font is licensed. Licensed fonts must not be modified or 


exchanged. If bit 1 is set, the font may not be embedded in a document. If bit 1 
is clear, the font can be embedded. If bit 2 is set, the embedding is read-only. 
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OUTLINETEXTMETRIC struct 


otmsCharSlopeRise 


otmsCharSlopeRun 


otmltalicAngle 
otmEMSquare 


otmAscent 
otmDescent 


otmLineGap 
otmsCapEmHeight 
otmsXHeight 
otmrcFontBox 
otmMacAscent 


otmMacDescent 


otmMacLineGap 
otmusMinimumPPEM 
otmptSubscriptSize 
otmptSubscriptOffset 


otmptSuperscriptSize 
otmptSuperscriptOffset 
otmsStrikeoutSize 
otmsStrikeoutPosition 


otmsUnderscoreSize 
otmsUnderscorePosition 
otmpFamilyName 


otmpFaceName 


Slope of the cursor. This value is 1 if the slope is vertical. Applications can use 
this value and the value of the otmsCharSlopeRun member to create an italic 
cursor that has the same slope as the main italic angle (specified by the 
otmltalicAngle member). 


Slope of the cursor. This value is zero if the slope is vertical. Applications can 
use this value and the value of the ofmsCharSlopeRise member to create an italic 
cursor that has the same slope as the main italic angle (specified by the — 
otmlItalicAngle member). 


Main italic angle of the font, in counterclockwise degrees from vertical. 
Regular (roman) fonts have a value of zero. Italic fonts typically have a 
negative italic angle (that is, they lean to the right). 


Number of logical units defining the x- or y-dimension of the em square for 
this font. (The number of units in the x- and y-directions are always the same 
for an em square). 


Maximum distance characters in this font extend above the base line. This is 
the typographic ascent for the font. 


Maximum distance characters in this font extend below the base line. This is 
the typographic descent for the font. 


Typographic line spacing. 
Not supported. 
Not supported. 
Bounding box for the font. 


Maximum distance characters in this font extend above the base fas for the 
Macintosh” computer. 


Maximum distance characters in this font extend below the base line for the 
Macintosh computer. 


Line-spacing information for the Macintosh computer. — 
Specifies the smallest recommended size for this font in pixels per em-square. 
Recommended horizontal and vertical size for subscripts in this font. 


Recommended horizontal and vertical offset for subscripts in this font. The 
subscript offset is measured from the character origin to the origin of the 
subscript character. 


Recommended horizontal and vertical size for superscripts in this font. 


Recommended horizontal and vertical offset for superscripts in this font. The 
superscript offset is measured from the character base line to the base line of 
the superscript character. 


_ Width of the strikeout stroke for this font. Typically, this is the width of the 


em-dash for the font. 


Position of the strikeout stroke relative to the base line for this font. Positive 
values are above the base line and negative values are below. 


Thickness of the underscore character for this font. 
Position of the underscore character for this font. 


Offset from the beginning of the structure to a string: Senne the family 
name for the font. 


Offset from the beginning of the structure to a string specifying the typeface 
name for the font. (This typeface name corresponds to the name specified in 
the LOGFONT structure.) 
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RGBQUAD struct 


otmpSty leName 


Offset fom the eas of the structure t to: a acting mer the styler name 
for the font. 


otmpFullName Offset from the beginning of the structure to a string specifying the full name 


for the font. This name is unique for the font and often contains a version 
number or other identifying information. 


RGBQUAD struct 


typedef struct tagRGBQUAD { 
BYTE rgbBlue; 

BYTE rgbGreen; 

BYTE rgbRed; 

BYTE rgbReserved; 
} RGBQUAD; 


Describes a color consisting of relative intensities of red, green, and blue. The following 
table describes the members. 


windows.h 


: Member — _ Description — : 
rebBlue a Intensity of blue - 
rgbGreen Intensity of green 
rgbRed Intensity of red 


rgbReserved Must be zero 


RGBTRIPLE struct 


typedef struct tagRGBTRIPLE { 
BYTE rgbtBlue; 

BYTE rgbtGreen; 

BYTE rgbtRed; 

} RGBTRIPLE; 


Describes a color consisting of relative intensities of red, green, and blue. 


windows.h 


tebtBlue Blue capi 
rgbtGreen Green intensity 
rebtRed Red intensity 


TEXTMETRIC struct 


windows.h 


The 16-bit version formatted and packed differently than the 32-bit version: 
typedef struct tagTEXTMETRIC { 

int tmHeight; 

int tmAscent; 


Appendix B, Windows API structs 733 


 TEXTMETRIC struct 


- int tmDescent; — 
int tminternalLeading; 
int tmExternalLeading; 
int tmAveCharWidth; 
int tmMaxCharWidth; 
int tmWeight; 
BYTE tmitalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmFirstChar, 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmPitchAndFamily; 
_ BYTE tmCharSet; 
int tmOverhang; 
int tmDigitizedAspectx; 
int tmDigitizedAspectY; 
} TEXTMETRIC; 


32-bit version: 
typedef struct tagTEXTMETRIC { 
LONG tmHeight; 
LONG tmAscent; 
LONG tmDescent; 
LONG tminternalLeading; 
LONG tmExternalLeading; 
LONG tmAveCharWicth; 
LONG tmMaxCharWidth; 
LONG tmWeight; 
LONG tmOverhang; 
LONG tmDigitizedAspectx; 
LONG tmDigitizedAspectY; 
BYTE tmFirstChar; 
BYTE tmLastChar; 
BYTE tmDefaultChar; 
BYTE tmBreakChar; 
BYTE tmltalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; | 
} TEXTMETRIC; : : 
Contains basic information about a physical font. All sizes are in logical units (mapping 
mode dependent). The table below describes the members. | 


tmHeight _ Height of character cells (f{mAscent + tmDescent). 
_ tmAscent Ascent of character cells (in units above base line). 
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‘ened : : as ean 


tmDescent | 
tminternalLeading 


tmExternalLeading 
tmAveCharWidth 

tmMaxCharWidth 

tmWeight 


tmltalic 
tmUnderlined 
tmStruckOut 
tmFirstChar 
tmLastChar 
tmDefaultChar 
tmBreakChar 
tmPitchAndFamily 


tmCharSet 


Descent of character cells (in units below base line). 


TEXTMETRIC struct 


Amount of leading (space) inside the bounds set by tmHeight. Diacritical 
characters occur in this area. 


Amount of extra leading (space) added between rows. Sometimes set to zero. 
Average width of characters in the font. Does not include overhang. 

Width of the widest character in the font. 

Font weight. Can be one of the following values: 


FW_DONTCARE FW_SEMIBOLD 
FW_THIN FW_DEMIBOLD 
FW_EXTRALIGHT FW_BOLD 


FW_ULTRALIGHT 
FW_LIGHT 
FW_NORMAL 
FW_REGULAR 
FW_MEDIUM 

Italic font if not 0 
Underlined font if not 0 
Struckout font if not 0 
Value of first character defined in font 
Value of last character defined in font 
Value of non-font substitution character 


FW_EXTRABOLD 
FW_ULTRABOLD 
FW_BLACK 
FW_HEAVY 


Word-break character value for text justification 


Pitch and family of the selected font. The four low-order bits identify the type of 
font, as follows: 


Value Meaning 
TMPF_FIXED_PITCH _ Fixed-pitch font. 
TMPF_VECTOR Vector or TrueType font. 
TMPF_TRUETYPE TrueType font. 
TMPF_DEVICE Device font. 


The four high-order bits of this member designate the font family. The 
tmPitchAndFamily member can be combined with the hexadecimal value OxF0 by 
using the bitwise AND operator and can then be compared with the font family 
names for an identical match. The following font families are defined: 


Value 
FF_ DECORATIVE 


Meaning 
Novelty fonts 


FF_DONTCARE Don't care or don't know 

FF_MODERN Fonts with constant stroke width, with or without serifs 
FF_ ROMAN Fonts with variable stroke width and with serifs 
FF_SCRIPT Fonts designed to look like handwriting 

FF_SWISS Fonts with variable stroke width and without serifs 


Specifies the character set of the font. The following values are defined: 
ANSLCHARSET 

DEFAULT_CHARSET 

SYMBOL_CHARSET 
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WNDCLASS struct 


SHIFTJIS_CHARSET 


| OEM_CHARSET 
tmOverhang Extra width that is added to some synthesized fonts 


tmDigitizedAspectX Horizontal aspect of the device for which the font was designed. The ratio of 
tmDigitizedAspectX and tmDigitizedAspectY is the aspect ratio of the device for 
which the font was designed. 


tmDigitizedAspectY Specifies the vertical aspect of the device for which the font was designed. The 
- ratio of tmDigitizedAspectX and tmDigitizedAspectY is the aspect ratio of the device 
for which the font was designed. 


typedef struct tagWNDCLASS { 
UINT _ style; 

WNDPROC IpfnWndProc; 

int cbClsExtra; 

int cbWndExtra; 

HANDLE hlinstance; 

HICON _hicon; 

HCURSOR hCursor; 

HBRUSH hbrBackground; 
LPCTSTR lpszMenuName; 
LPCTSTR lpszClassName; 
} WNDCLASS; 

Contains TWindow class registration attributes, described in the following table: 


style Class style. Can be any combination of the following values: 
| Value Meaning 
CS_BYTEALIGNCLIENT Aligns the window's client area on the byte boundary 
(in the x direction). 


CS_BYTEALIGNWINDOW Aligns a window on a byte boundary (in the x 
direction) to enhance performance during operations 
that involve moving or sizing the window. This style 
affects the width of the window and its horizontal 
position on the display. 

CS_CLASSDC Allocates a device context (DC) to be shared by all 
windows in the class. 


-CS_DBLCLKS Sends double-click messages to the window 
procedure while the cursor is within a window 
belonging to the class. 


CS_GLOBALCLASS Allows an application to create a window of the class 
regardless of the value of the hInstance parameter 
used at window creation. 


lpfnWndProc Points to the window procedure. 


cbClsExtra Number of extra bytes to allocate following the window-class structure. The operating 
system initializes the bytes to zero. 


cbWndExtra Number of extra bytes to allocate following the window instance. Initializedt to 0. 
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‘Member 
hinstance 
hIcon 


hCursor 


hbrBackground 


lpszMenuName 


lpszClassName 


PAINTSTRUCT struct 


ee OR oo cco seinen ieee ccs 

Identifies the instance that the window procedure of this class is within. 

Identifies the class icon. Must be a handle of an icon resource. If NULL, an application 
must draw an icon whenever the user minimizes the application's window. 


Identifies the class cursor. Must be a handle of a cursor resource. If NULL, an 
application must set the cursor shape whenever the mouse moves into the application's 
window. 


Identifies the class background brush. Can be a handle to the physical brush to be used 
for painting the background, or it can be a color value. A color value must be one of the 
standard system colors listed below, plus 1. If a color value is given, you must convert it 
to one of the following HBRUSH types: 


COLOR_ACTIVEBORDER COLOR_HIGHLIGHTTEXT 
COLOR_ACTIVECAPTION COLOR_INACTIVEBORDER 
COLOR_APPWORKSPACE COLOR_INACTIVECAPTION 
COLOR_BACKGROUND COLOR_MENU 


COLOR_BTNFACE COLOR_MENUTEXT 
COLOR_BTNSHADOW COLOR_SCROLLBAR 
COLOR_BTNTEXT COLOR_WINDOW 
COLOR_CAPTIONTEXT COLOR_WINDOWFRAME 
COLOR_GRAYTEXT COLOR_WINDOWTEXT 


COLOR_HIGHLIGHT 


An application should not delete these brushes, because a class may be used by 
multiple instances of an application. 


When this member is NULL, an application must paint its own background whenever 
it is requested to paint in its client area. 


Points to a null-terminated character string that specifies the resource name of the class 
menu, as the name appears in the resource file. If NULL, windows belonging to this 
class have no default menu. 


Points to a null-terminated string or is an atom that specifies the window class name. 


PAINTSTRUCT struct windows 


16-bit version: 


typedef struct tagPAINTSTRUCT { 


HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 


BOOL flncUpdate; 


BYTE rgbReserved|[16]; 


} PAINTSTRUCT; 


32-bit version: 


typedef struct tagPAINTSTRUCT { 


HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
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PALETTEENTRY struct. 


BOOL fincUpdate; 
BYTE rgbReserved|[32]: 
} PAINTSTRUCT; 


Contains information needed by an application to paint the client area of a window. 


hdc The display device context used for painting. 

fErase If non-zero erase the background. 

rcPaint Specifies the upper-left and lower-right corners of the rectangle to be painted. 
fRestore Reserved. 

fIncUpdate Reserved. 

rgbReserved Reserved. 


PALETTEENTRY struct 


typedef struct tagPALETTEENTRY { 


BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 

} PALETTEENTRY; 


windows.h 


Specifies the color and usage of an entry in a logical color palette (see LOGPALETTE 
struct). The following table describes the settings: 


peRed Specifies a red intensity value for the palette entry. 
peGreen Specifies a green intensity value for the palette entry. 
peBlue Specifies a blue intensity value for the palette entry. 
peFlags Specifies how the palette entry is to be used. The peFlags member may be set to NULL or one 
) of these values: | 
Value Meaning 
PC_EXPLICIT The low-order word of the iegeal palette entry designates a 


PC_NOCOLLAPSE 


PC_RESERVED 


XFORM struct 


typedef struct tagXFORM { 
FLOAT eM11; 


738 ObjectWindows Reference Guide 


hardware palette index. This flag allows the application to show 
the contents of the display device palette. 


The color is placed in an unused system palette entry instead of 
being matched to an existing system palette color. 


Specifies that the logical palette entry be used for palette 
animation, preventing other windows from matching colors to the 
palette entry since the color frequently changes. If an unused 
system-palette entry is available, this color is placed in that entry. 
Otherwise, the color is available for animation. 


windows.h 


XFORM struct 


FLOAT eM12; 

FLOAT eM21; 

FLOAT eM22; 

FLOAT eDx; 

FLOAT eDy; 

} XFORM; 

Specifies a world-space to page-space transformation. The following table describes the 
members. | | | 


eM11 Specifies the following: 
Value Meaning 
Scaling Horizontal scaling component 
Rotation Cosine of rotation angle 
Reflection Horizontal component 
eM12 Specifies the following: 
Value Meaning 
Shear Horizontal proportionality constant 
Rotation Sine of the rotation angle 
eM21 Specifies the following: 
Value Meaning 
Shear Vertical proportionality constant 
Rotation Negative sine of the rotation angle 
eM22 Specifies the following: 
Value Meaning 
Scaling Vertical scaling component 
Rotation Cosine of rotation angle 
Reflection Vertical reflection component 
eDx Specifies the horizontal translation component. 
eDy Specifies the vertical translation component. 
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Symbols 


!= operator 
TCharSet 83 
TPoint 688 
TRect 694 
TRegion 386 
TSize 699 

& operator 
TRect 694 

&= operator 
TBitSet 70 
TRect 695 
TRegion 386 

* operator 
TAutoObject 584 
TPointer<> 689 

+ operator 
TPoint 687 
TRect 694 
TSize 698 

++ operator 
TOcFormatListlter 616 


TOcPartCollectionIter 634 


+= operator 
TBitSet 70 
TPoint 688 
TRect 694 
TRegion 386 
TSize 699 

<< operator 
TBitmap 67, 68 
TDib 173 
TMetaFilePict 302 
TPalette 349 
TPoint 688 
TRect 695 
TResId 697 
TSize 699 

-= operator 
TBitSet 70 
TPoint 688 
TRect 695 
TRegion 386 
TSize 699 

= operator 
TAutoObject 584 
TAutoObjectByVal 585 
TAutoObjectDelete 586 
TAutoString 593 
TAutoVal 595 
TCelArray 81 
TLocaleString 278 


Index 


TMenu 292 
TOcScaleFactor 641 
TPointer<> 689 
TRegion 386 
TStatus 412 

== operator 
TColor 100 
TCursor 122 
TDib 173 
TModule 309 
TOcFormatName 617 
TOcPart 626 
TPoint 688 
TRect 694 
TRegion 386 
TSize 699 

-> operator 
TPointer<> 689 

>> operator 
TPoint 688 
TRect 695 
TResId 697 
TSize 699 

[] operator 
TAutoStack 591 
TCelArray 81 
TOcFormatList 615 
TOcNameList 625 
TSortedStringArray 410 
TStatusBar 414 

= operator 
TRegion 387 

| operator 
TRect 694 

|= operator 
TBitSet 70 
TRect 695 
TRegion 387 

~ operator 
TBitSet 71 

- operator 
TPoint 687 
TRect 694 
TSize 698 


Numerics 
3-D support 163, 166 


A 


ABC struct 707 


abort dialog box 372 
canceling 372 
controls 372 
creating 370 
AbortDoc member function 
TPrintDC 356 
Above member function 
TEdgeConstraint 190 
Absolute member function 
TEdgeConstraint 190 
TEdgeOrSizeConstraint 192 
abstract data validation 436 
accelerator tables 495 
handles, returning 307 
loading into memory 307 
accelerators 605 
resource [Ds 41 
AccelTable data member 
TWindowAttr 495 
AccessResource member 
function 
-TModule 304 
Activate member function 
TButtonGadget 77 
TOcPart 626 
ActivatePart member functio 
TOcView 646 
activating objects 626, 630, 646 
Add member function 
TAppDictionary class 54 
TOcFormatList 614 
TOcNameList 625 
TOcPartCollection 632 
TSortedStringArray 408 
AddItem member function 
TVbxControl 442 
AddString member function 
TComboBox 103 - 
TComboBoxData 107 
TListBox 265 
TListBoxData 271 
AddStringltem member function 
TComboBoxData 107 
TListBoxData 271 
AddUserFormatName member 
function 
TOcApp 601 
TOleFrame 317 
AdjustWindowRect member 
function ; 
TWindow 457 
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_ AdjustWindowRectEx member 
function | 
TWindow 457 
Ageregate member function 
TUnknown 658 
ageregating objects 658 
ageregation 
COM objects 552, 555 
Align data member 
TTextGadget 423 
Alloc member function 
TOleAllocator 653 
allocation 
edit control error 
message 200 
allocator, specifying 652 
AllocResource member function 
TModule 305 
AngleArc member function 
TDC 123 


AnimatePalette member function. . 


TPalette 348 
animation 80 | 
AntialiasEdges data member 
TButtonGadget 76 
AppDesc data member 
TRegistrar 657 
AppDesc member function 
TRegistrar 655 
appdict.h 19 
AppendMenu member function 
TMenu 289 
applicat.h 19 
application classes 13 
application dictionary macro 31 
applications 
event messages 565 
facilitating 117 
Arc member function 
TDC 123 
Area member function 
TRect 691 
ArgCount data member 
TAutoStack 591 
ArgsymbolCount data member 
TAutoStack 591, 592 


arguments 


automation servers 548, 571 - 


registering 549 
Arrangelcons member function 
TMD!Client 281 
arrays 
bitmap images 68 
cels 80 | 
ArraySize member function 
TSortedStringArray 408 


ASCII strings, sorting 408 
Aspect data member 
TOcViewPaint structure 651 

aspectall registration key 536 
aspectcontent registration 

key 536 
aspectdocprint registration 

key 537 
aspecticon registration key 537 


aspects, presentation 566, 569, 


608 — 
aspectthumbnail registration 
key 537 
assignment 
automated objects 594, 595 
AssignMenu member function 
TFrameWindow 223 
asxxxx constants 546 
AtMouse data member 
TGadgetWindow 239 
attaching streams to 
documents 189 
AttachStream member function 
TDocument 189 
AttachTemplate member 
function : 
TDocManager 178 
Attr data member 
TAutoCommand 577 
TDialog 164 
TWindow 455 
attributes 
caption bars 424 
client windows 281 
document properties 48 
edit controls 197 
setting 193 
file 343 
find-and-replace 216, 217 
atxxxx constants 540 
AUTOARGS macros 538 
AUTOCALL_xxxx macros 538 
_AUTOCLASS macro 539 » 
autocreation. 
interface elements 
enabling 464 
interface objects 
disabling 463 
AUTODATA macros 539 
AutoDataType enum. 540 
AUTODETACH macro 540 
AUTOENUM macros 541 
AUTOFLAG macros 541 
AUTOFUNC macros 542 
AUTOINVOKE macro 543 
AUTOITERATOR macros 543 
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-automacr.h 538 


automated methods 
return values 574 a 

automating collections 631, 633 

automating objects 525, 526 
collections 543, 557, 581 

enumerating 579 
verbs, registering 568, 569, 
570, 665, 666 


~ automation 


class modifier 539 
data types 525, 541 
flags 540 
definition blocks 555 
ObjectComponents 
classes 523, 524 
automation controllers 538, 544 
accessing members 556 
derived classes 587 
proxy macros 528 
stack, processing 590 
automation servers 
accessing members 539, 542, 
546 
accessing properties 545, 
559, 560 
arguments 571 
registering 549 
verifying 548 
bit flags 541 
combining unrelated 
classes 556, 557 
copying objects 585 | 
declaration macros 525, 526 
defining automatable 
members 551, 552, 555 
destroying objects 540 
enumerated types 541 
exposing applications 556 
exposing members 558 
exposing objects 547 
hooks 543, 548 
creating record of 545 
defined 539 
error handling 546 
executing 527 
preventing 544 | 
reversing commands 548 
iteration 543, 557 
stack 594 
AutoMode data member 
TScroller 395 : 
AUTONAMES macros 544 
AUTONOHOOK macro 544 
AutoOrg data member 
TScroller 395 


AUTOPROP macros 545 


-AUTORECORD macro 545 
AUTOREPORT macro 546 
AutoScroll member function 
TScroller 396 
AUTOSTAT macros 546 
AutoSymFlag enum 546 
AUTOTHIS macros 547 
AUTOUNDO macro 548 
AUTOVALIDATE macro 548 


BandInfo member function 


TPrintDC 356 

Banding data member 
TPrintout 375 

banding flags 375 

banding printouts 374, 375 

BandRect data member 
TPrinter 370 

BarColor data member 
TGauge 244 

beeps 200 

BEGIN REGISTRATION. macro 
674 

BeginDocument member 

function 

TPrintout 373 

BeginModal member function 
TApplication 57 

BeginPath member function 
TDC 123 

BeginPressed member function 
TButtonGadget 77 

BeginPrinting member function 
TPrintout 373 

BeginView member function 
TScroller 396 

Below member function 
TEdgeConstraint 191 

BF_CHECKED constant 28 

BF_GRAYED constant 28 

BF_UNCHECKED constant 28 

Bind member function 
TAutoEnumerator 579 
TAutoProxy 588 

bit counts 47 

bit flags 
automation servers 541 

bit masks 496 

BitBlt member function 
TDC 123 

Bitmap data member 
TCelArray 82 

bitmap images, ea 68 

BITMAP struct 708 


BITMAPCOREHEADER 
struct 709 
BITMAPCOREINEFO struct 709 
bitmapga.h 20 
BITMAPINFO struct 710 
BITMAPINFO() operator 
TDib 170 
BITMAPINFOHEADER 
struct 712 
BITMAPINFOHEADER() 
operator 
TDib 170 
BitmapOrigin data member 
TButtonGadget 76 
bitmaps 65 
deleting 80 
loading into memory 307 
referencing 81 
user interface 80 
bits, setting and clearing 69 
Bits data member 
TDib 174 
bitset.h 20 
BitsPixel member function 
TBitmap 66 
Bkcolor data member 
TSlider 404 
BkgndBrush data member 
TGadgetWindow 239 
BkgndColor data member 
TWindow 489 
Black data member 
TColor 99 
blocks 
automation definition 555 
Blue member function 
TColor 100 
BMSetStyle member function 
TButton. 73 
BN_CLICKED constant 28 
BN_DISABLE constant 28 
BN_DOUBLECLICKED 
constant 28 
BN_HILITE constant 28 
BN_PAINT constant 28 
BN_UNHILITE constant 28 
BNClicked member function 
TCheckBox 85 
TRadioButton 383 
BOleComponentCreate member 
function 
TOcRegistrar 635 
bool types 24 
bool() operator 
TClipboard 95 
Boolean types 574 


Border data member 
TTinyCaption 425 
borders 432 
hatched 432 
patterns 432 
status bars, setting 415 
Borders data member 
TGadget 232 
BorderStyle data member 
TStatusBar 415 
BottomLeft member function 
TRect 691 
BottomRight member function 
TRect 692 
Bounds data member 
TGadget 232 
BreakMessageLoop data 
member 
TApplication 61 
BringWindow ToTop member 
function 
TWindow 458 
broadcasting messages 459 
Browse member function 
TOcApp 601 
BrowseClipboard member 
function 
TOcApp 602 
TOcView 646 
BrowseLinks member function 
TOcView 646 
brushes, handles, converting 72 
BS_DEFPUSHBUTTON 
constant 73 
BS_GROUPBOxX style 251 
BS_ PUSHBUTTON constant 73 
BS_RADIOBUTTON 
constant 382 
buffer data member 
TInputDialog 255 
buffers 
retrieving handles 194, 197 
text 193, 194 
transfer data 256, 270, 394, 
410, 411, 485, 488 
constants 432 
enabling 464 
pointer to 490 
size, returning 463 
transfer, combo boxes 106 
transferring data to 432 
writing to 271 
BufferSize data member 
TInputDialog 255 
BuffSize data member 
TFindReplaceDialog::TData 
218 
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BuildCelArray member function. 


TButtonGadget 77 
_~BUILDOWLDLL macro 49 
— building ObjectWindows 
libraries 18 
—~BUILDOWLDLL macro 18 
button flag constants 28 — 
button message constants 28 
button.h 20 
buttonga.h 20 
buttons, settings 74: 
BWCC templates 163 
BWCCEnabled member function 
TApplication 57 
bytes, transfer data 410, 411, 463 


C 


CalcBandingFlags member 


function 
TPrinter 371 
CalcPlaySize member function 
TMetaFilePict 302 
callback factory code 38 
— callback functions 309, 599 
CancelPressed member function 
TButtonGadget 78 
CanClear member function 
TEditFile 202 
CanClose member function 
TApplication 57 
TDocument 184 
TEdit 198 
TEditFile 202 
TEditView 206 
TListView 273 
TOcApp 602 
TOleDocument 312 
TOleFrame 318 
TOleView class 324 
TOleWindow 330 
TWindow 458 
TWindowView 498 
CanDirty data member 
TOcVerb 644 
CanUndo member function 
TEdit 193 
CanUnload member function 
TOcKRegistrar 636. 
TRegistrar 654 
caption bars 
activating 427 
close boxes 425, 430 
creating 425 
closing 425 
creating 424 
default 424 


dimensions | 
returning 427, 428, 429 
setting 426 
minimizing 427, 430 
painting 427, 429, 430 
CaptionFont data member 
TTinyCaption 425 
CaptionHeight data member 
TTinyCaption 425 
captions 62, 118, 285 
dialog box 255 
document 453 
setting 167, 482 
window 456, 474 
Capture data member 
TGadgetWindow 239 
CaretRect data member 
TSlider 404 
carets | 
creating system 460 
position, returning 195, 197 
carriage returns 194 
CascadeChildren member 
function 
TMD!IClient 282 
cascading windows 282 
case-insensitive searches 197 
case-sensitive searches 197 
catch keyword 502 | 
CBN_CLOSEUP constant 28 
CBN_DBLCLK constant 28 
CBN_DROPDOWN constant 28 
CBN_EDITCHANGE | 
constant 28 
CBN_EDITUPDATE 
constant 28 
CBN_ERRSPACE constant 28 
CBN_KILLFOCUS constant 28 
CBN_SELENDCANCEL 
constant 29 
CBN_SELENDOK constant 29 
CBN_SETFOCUS constant 29 
CBS_AUTOHSCROLL 
constant 102 
CBS DROPDOWN constant 102 
CBS_DROPDOWNLIST 
constant 102 
CBS OWNERDRAWFIXED 
constant 102 
CBS_SIMPLE constant 102 
CBS_SORT constant 102 
cc data member 
TChooseColorDialog 86 
CC _FULLOPEN constant 88 
CC _PREVENTFULLOPEN 
constant 88 
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CC _RGBINIT constant 88 


CC SHOWHELP constant 88 


CDERR_DIALOGFAILURE 
constant 88, 90, 345 
CDERR_FINDRESFATLURE 
constant 88, 90 
CDERR_LOADRESFAILURE 
constant 88, 90, 218, 345 
CDERR_LOADSTRFAILURE 
345 
CDERR_ LOADSTRFAILURE 
constant 88, 90, 219 
CDERR_LOCKRESOURCE- 
FAILURE constant 88, 90, 218, 
345 
CDERR_REGISTERMSGFAIL 
constant 219 
CDTitle data member 
TCommonDialog 113 
CeEditConvert member function 
TOleWindow 330 
CeEditCopy member function 
TOleWindow 330 
CeEditCut member function 
TOleWindow 331 
CeEditDelete member function 
TOleWindow 331 
CeEditInsertObject member 
function 
TOleWindow 331 
CeEditLinks member function 
TOleWindow 331 | 
CeEditObject member function 
TOleWindow 331 
CeEditPaste member function 
TOleWindow 331 
CeEditPasteLink member 
function 
TOleWindow 331 
CeEditPasteSpecial member 
function 
TOleWindow 331 
CeEditVerbs member function 
TOleWindow 331 
CeFileClose member function 
TOleWindow 332 
CelArray data member 
TButtonGadget 76 
celarray.h 20 
CelOffset member function 
TCelArray 81 
CelRect member function 
TCelArray 81 


-~CelSize member function 


TCelArray 81 


cf data member 
TChooseFontDialog 89 
CF ANSIONLY constant 90 
CF APPLY constant 90 
CF BOTH constant 90 
CF _ EFFECTS constant 90 
CF FIXEDPITCHONLY 
constant 90 
CF FORCEFONTEXIST 
constant 90 
CF _ INITTOLOGFONTSTRUCT 
constant 90 
CF LIMITSIZE constant 90 
CF NOSIMULATIONS 
constant 90 
CF _PRINTERFONTS 
constant 90 
CF SCALABLEONLY 
constant 90 
CF_SCREENFONTS constant 90 
CF SHOWHELP constant 90 
CF TTONLY constant 91 
CF USESTYLE constant 91 
CF WYSIWYG constant 91 
CFERR_ MAXLESSTHANMIN 
constant 90 
CFERR_NOFONTS constant 90 
chains (documents) 189 
ChangeModeToPal member 
function 
TDib 170 
ChangeModeToRGB member 
function 
TDib 171 
char far*() operator 
TResId 697 
char*() operator 
TAutoString 593 
character sets 567 
characters 
edit control and 192, 195, 201 
end-of-line 194 
formatting into buffer 193, 
194 
invalid 
checking for 215, 422, 437 
numeric values 383 
picture formats 381 
number scrolled 196 
user-Input 256 
valid 
input fields 215 
picture formats 381 
check boxes 
selection box state 28 
status 84 


Check member function 
TCheckBox 84 
TXOle 663 
TXRegistry 664 
checkbox.h 20 
CheckDlgButton member 
function 
TWindow 459 
checking user input 215, 278 
data entry 436 
input fields 421 
numeric values 383 
picture strings 380 
checkmarks 28, 251 
radio buttons 382 
CheckMenultem member 
function 
TMenus 289 
CheckRadioButton member 
function 
TWindow 459 
CheckState enum 111 
CheckValid member function 
TDC 159 
TGdiObject 248 
TMenu 289 
child ID constant 45 
child lists 
child windows and 460 
deleting objects 457, 463 
interface element and 161, 
227, 493 
interface object IDs and 469 
removing objects 484 
test iteration and 466 
transfer buffer and 490 
child windows 459 
cascading 282 
closing 282 
creating 165, 256, 258, 279, 
281, 282 
decorating 162 
first 469 
iterator member 
functions 466 
last 470 
next 478 
number of 478 
previous 479 
tiling 283 


ChildBroadcastMessage 


member function 
TWindow 459 
ChildDoc data member 
TDocument 183 


ChildWindowFromPoint 
member function 
TWindow 459 
ChildWithId member function 
TWindow 459 
chooseco.h 20 
choosefo.h 20 
Chord member function 
TDC 124 
Cld data member 
TOcInitInfo 619 
classes 
event handling 31 
names 
client window 
registration 284 
edit controls 
registration 200 
interface objects 
registration 491 
list boxes registration 270 
modal and modeless 
dialog box 167 
static control 
registration 412 
scope resolution operator 3 
windows 
input dialog windows 256 
Windows registration 480 
ClassInfo data member 
TAutoBool 574 
TAutoCurrency 577 
TAutoDate 578 
TAutoDouble 578 
TAutoFloat 580 
TAutoLong 584 
TAutoShort 590 
TAutoString 594 
TAutoVoid 599 
_CLASSTYPE macro 494 
CleanupWindow member 
function 
TOleFrame 318 
TOleWindow 332 
TWindow 491 
Clear member function 
TAutoEnumerator 579 
TAutoVal 596 
TComboBox 103 
TComboBoxData 107 
TEdit 193 
TListBoxData 271 
TOcFormatList 615 
TOcNameList 625 
TOcPartCollection 632 
TStatic 411 
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ClearContainerGroupCount 
member function 
TMenuDescr 297 
ClearDevice member function 
TPrinter 369 
ClearDevMode member function 
TPrintDialog::TData 366 
ClearDevNames member 
function 
TPrintDialog::TData 366 
ClearFlag member function 
TAutoCommand 575 
TDocTemplate 679 
TWindow 459 
clearing bits 69 
clearing flags 69 
ClearList member function 
TComboBox 103 
TListBox 265 
ClearModify member function 
TEdit 193 
ClearServerGroupCount 
member function 
TMenuDescr 297 
client windows 159, 225 
arranging icons 281 
attributes 281 
cascading children 282 
closing children 282 
handles, returning 306 
moving through 222 
registration class name 284 
tiling children 283 
ClientAttr data member 
TMDi!IClient 281 
ClientSize data member 
TLayoutWindow 264 
ClientToScreen member function 
TWindow 459 
ClientWnd data member 
TFrameWindow 225 
Clip data member 
TGadget 229 
TOcViewPaint structure 651 
Clip member function 
TOcApp 602 
clipboar.h 20 
Clipboard 
constants 600 
text and 193, 194, 196 
viewer chain 97 


windows 
adding 96, 98 
identifying 94 


owner 94,95 
removing 98 


Windows API 
encapsulation 92 
Clipboard formats — 
name strings 624 
registering 561, 567, 601, 603, 
648 


supported by application 614 
clipview.h 20 
Clone member function 
TDocTemplate 680 
TDocTemplateTD,V 684 
TGdiObject::TXGdi 250 
TXBase 700 
TXCompatibility 500, 501 
TXInvalidMainWindow 63 
TXInvalidModule 310 
TXOutOfMemory 501 
TXOwl1 504 
TXWindow 499 
close boxes, creating 425, 430 
Close member function 
TDocument 184 
TFileDocument 211 
TMetaFileDC 301 
TOcDocument 610. 
TOcPart 627 
TStorageDocument 417 
CloseBox data member 
TTinyCaption 425 
CloseChildren member function 
TMD!IClient 282 
CloseClipboard member 
function 
TClipboard 93 
CloseFigure member function 
TDC 124 
CloseThisFile member function 
TFileDocument 213 
CloseWindow member function 
TDialog 164 
TWindow 459 
clsid registration key 548 
CM_ARRANGEICONS 
constant 31, 283 


(CM_CASCADECHILDREN 


constant 31, 283 . 
CM_CLOSECHILDREN 
constant 31, 283 
CM CREATECHILD 
constant 31, 283 
CM_EDITCLEAR constant 29 
CM_EDITCONVERT 
constant 30 — 
CM _EDITCOPY constant 29 
CM_EDITCUT constant 29 


CM_EDITDELETE constant 29 
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CM_EDITFIND constant 30 
CM_EDITFINDNEXT 
constant 30 
CM_EDITFIRSTVERB 
constant 30 
CM_EDITINSERTOBJECT 
constant 30 
CM_EDITLASTVERB 
constant 30 
CM_EDITLINKS constant 30 
CM_EDITOBJECT constant 30 
CM_EDITPASTE constant 29 
CM_EDITPASTELINK 
constant 30 
CM_EDITPASTESPECIAL 
constant 30 7 
CM_EDITREPLACE constant 30 
CM _EDITUNDO constant 29 
CM_EXIT constant 29, 460 
CM_FILECLOSE constant 29 
CM_FILENEW constant 29 
CM_FILEOPEN constant 29 
CM_FILEPRINT constant 29 
CM_FILEPRINTERSETUP 
constant 29 
CM_FILEREVERT constant 29 
CM_FILESAVE constant 29 
CM_FILESAVEAS constant 29, 
202 
CM_TILECHILDREN 
constant 31 
CM_TILECHILDREN 
message 283 
CM_TILECHILDRENHORIZ 
constant 31 
CM_VIEWCREATE constant 29 
CMArrangelcons member 
function 
TMD!IClient 283 
CmCancel member function. 
TDialog 164 
TFindReplaceDialog 217 
CmCascadeChildren member 
function | 
TMD!Client 283 
CmCharsEnable member 
function 
TEdit 199 
CmChildActionEnable member 
function | 
TMD!IClient 283 
CmCloseChildren member 
function 
TMD!IClient 283 


CmCreateChild member 
function 
TMD3!IClient 283 
cmdline registration key 549 
CmEditAdd member function 
TListView 274 
CMEditClear member function 
TEdit 199 
CmEditClear member function 
TListView 274 
CmEditConvert member 
function 
TOleWindow 332 
CmEditCopy member function 
TEdit 199 
TListView 274 
TOleWindow 332 
CmEditCut member function 
TEdit 199 
TListView 274 
TOleWindow 332 
CmEditDelete member function 
TEdit 199 
TListView 274 
TOleWindow 332 
CmEditFind:member function 
TEditSearch 205 
CmEditFindNext member 
function 
TEditSearch 205 
CmEditInsertObject member 
function 
TOleWindow 332 
CmEditItem member function 
TListView 274 
CmEditLinks member function 
TOleWindow 332 
CmEditPaste member function 
TEdit 199 
TListView 274 
TOleWindow 332 
CmEditPasteLink member 
function 
TOleWindow 332 
CmEditPasteSpecial member 
function 
TOleWindow 333 
CmEditReplace member 
function 
TEditSearch 205 
CmEditUndo member function 
TEdit 199 
TListView 274 
CmExit member function 
TWindow 460 


CmFileClose member function 
TDocManager 178 
TOleWindow 333 

CmFileNew member function 
TDocManager 178 
TEditFile 202 

CmFileOpen member function 
TDocManager 178 
TEditFile 202 

CmFileRevert member function 
TDocManager 178 

CmFileSave member function 
TDocManager 178 
TEditFile 202 

CmFileSaveAs member function 
TDocManager 178 
TEditFile 202 

CmFindNext member function 
TFindReplaceDialog 217 

CmFontApply member function 
TChooseFontDialog 89 

CmHelp member function 
TCommonDialog 113 

CmLbSelChanged member 

function 
TOpenSaveDialog 343 

CmModEnable member function 
TEdit 199 

CmOk member function 
TDialog 165 
TOpenSaveDialog 343 

CmOkCancel member function 
TCommonDialog 113 

CmPasteEnable member 

function 
TEdit 199 

CmReplace member function 
TFindReplaceDialog 217 

CmReplaceAll member function 
TFindReplaceDialog 217 

CmSelChange member function 
TListView 275 

CmSelectEnable member 

function 
TEdit 200 

CmSetup member function 
TPrintDialog 369 

CmTileChildren member 

function 
TMD!IClient 283 
CmTileChildrenHoriz member 
function 
TMD!IClient 283 

CmViewCreate member function 
TDocManager 178 | 

color counts 47 


Color data member 
TChooseColorDialog::TData 
87 
TChooseFontDialog::TData 
90 
color.h 20 
color-matching functions 378 
COLORREF typedef 713 
COLORREF() operator 
TColor 100 
colors, selecting 86 
COM objects 
aggregating with 552, 555 
creating 551, 553, 658 
implementing [Unknown 658 
combo boxes 
creating 102 
entries, transferring 106 
interface element 102 
lists, showing 105 
messages 28 
owner-draw 118 
position, relative to origin 102 
styles 102 
combobox.h 20 
command line processing 656 
command objects 590 
command-based message 
constants 29, 30,31 
CommandEnable member 
function 
TButtonGadget 75 
TGadget 230 
commdial.h 20 
CommDIgExtendedError 
codes 218 
Commit member function 
TDocument 184 
TFileDocument 211 
TOleDocument 312 
TStorageDocument 417 
Compare member function 
TLocaleString 277 
Compareltem member function 
TControl 118 
COMPAREITEMSTRUCT 
struct 714 
compat.h 20 
compiler options for building 
libraries 17 
complement operator 
TBitSet 71 
Component Object Model See 
COM objects 
compound documents 
loading and saving 609 
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concatenating strings 271 
Condemn member function — 
TAppDictionary class 54 
_ TApplication 58 
configuring printers 367, 370 
connector objects 600 
parts 626 
remote views 637 
views 645 
const char far*() operator 
TAutoString 593 
const char* operator 
TLocaleString 277 
constants 
attribute masks 496 
buffer, transfer data 432 
button flags 28 
button messages 28 
child ID 45 
— Clipboard 600 
combo box messages 28 
dialog control messages 33 
dispatch IDs 592 
_ document manager mode 33 
document message 34 
document string IDs 42 
document template 34 
edit file 29 
edit fileID 43 
edit messages 35 
edit replace 30 
edit view 30, 42 
edit view ID 42 
editing 29 
exception messages 43 
file 40 
list view ID 44 
MDI functions 31 
printer 41 
printer string ID 44 
registration tables 533 
resource IDs _ 
accelerator keys 41 
menu commands 41 
mode indicators 42 
OLE accelerator keys 41 
ole menu commands 41 
transfer functions 432 
validator ID 44 
constraints 
defined 258 
edge 190, 258, 261 
— layout 256, 258 
ConstructDoc member function 
TDocTemplate 680 


constructors (predefined classes) 


TAutoCommand 574 
TAutoDate 578 
TAutoEnumerator 579 
TAutolterator 583 
TAutoObject 584 
TAutoObjectByVal 586 
TAutoObjectDelete 586 
TAutoProxy 589 
TAutoStack 591 
TAutoString 592 
TDocument::List 189 
TOcApp 606 | 
TOcDocument 610 
TOcFormatList 614 
TOcFormatListlter 616 
TOcFormatName 617 
TOcInitInfo 620 
TOcModule 623 
TOcNameList 624 
TOcPart 626 
TOcPartCollection 632 
TOcPartCollectionlter 633 
TOcRemView 637 
TOcVerb 644 
TOcView 645 
TOleAllocator 652 
TUnknown 659 
TWindow 491 
TXAuto 660 
TXObjComp 662 
TXOle 663 
TXRegistry 664 
ConstructView member function 
TDocTemplate 680 
container classes 
compound documents 
and 609 
embedded object classes 626, 
645 | 
Container data member 
TOcInitInfo 618, 620 
container view 323 
ContainerName data member 
TOleWindow 329 
Contains member function 
TRect 692 
TRegion 385 
content aspect 608 
control bars 115 
control classes 12 | 
Control data member 
TControlGadget 116 
control interface elements 117 
controLh 20 
controlb.h 20 
controlg.h 20 
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controls 117, 119 
drawing 118, 119 
IDs 40 
retrieval 166 - 
managing 251 
VBX 440, 447 
conversions 
objects 602 
scroll bar values 46 
Convert member function 
TOcApp 602 
coordinate systems, 
translating 310 
coordinates 
device points 310 
logical points 310 
viewport 310 
Copies data member 
TPrintDialog::TData 364 
Copy member function 
TAutolterator 581 
TAutoVal 596 
TEdit 193 
TOcRemView 638 
TOcView 646 
CopyCursor member function 
TModule 305 
Copylcon member function 
TModule 305 
copying exception objects 
TXBase class 700 
‘TXCompatibility class 500 
TXGdi class 250 
TXInvalidMainWindow 
class 63 
TXInvalidModule class 310 
TXMenu class 501 
TXOutOfMemory class 501 
TXOwl class 504 
TXWindow class 499 
copying objects 585, 602, 638 
embedded 646 
Count member function 
TOcFormatList 615 
TOcNameList 625 
TOcPartCollection 632 
CountClipboardFormats 
member function 
TClipboard 93 
cracking Windows 
messages 513 
Create member function 
TAutoFactory 64 
TBitmap 68 
TDialog 165 
TEditView 206 
TGadgetWindow 241 


TListView 273 
TMD!IClient 282 
TOleFactoryBase 315 
TPalette 350 
TWindow 460 
CreateAbortWindow member 
function 
TPrinter 371 
CreateAnyDoc member function 
TDocManager 178 
CreateAnyView member 
function 
TDocManager 179 
CreateApp member function 
TAutoFactory 64 
TOleFactoryBase 315 
CreateCaret member function 
TWindow 460 
CreateChild member function 
TMD!Client 282 
CreateChildren member function 
| TWindow 460 
CreateDoc member function 
TDocManager 179 
TDocTemplate 680 
TDocTemplateTD,V 684 
CreateObject member function 
TOleFactoryBase 316 
CreateOcApp member function 
TOcRegistrar 636 
CreateOcView member function 
TOleView class 324 
TOleWindow 333 
CreateVerbPopup member 
function 
TOleWindow 333 
CreateView member function 
TDocManager 179 
TDocTemplate 680 
TDocTemplateTD,V 684 
creating 
DC wrappers 122 
dialog boxes 
abort 370, 372 
print setup 368 
status bars 413, 414 
CSize data member 
TCelArray 82 
CTL3D DLL support 58, 163 
Ctl3dEnabled member function 
TApplication 58 
currency 577 
Current member function 
TOcFormatListIter 616 
TOcPartCollectionIter 634 
CurrentArg data member 
TAutoStack 591 


CurrentPreviewFont data 
member 
TPrintPreviewDC 379 
CursorModule data member 
TWindow 490 
CursorResId data member 
TWindow 490 
cursors 121 
loading into memory 308 
position, inserting text at 
current 196 
CustColors data member 
TChooseColorDialog::TData 
87 
CustomFilter data member 
TOpenSaveDialog::TData 345 
Cut member function 
TEdit 194 


D 


data 536, 566 
Clipboard, retrieving 94 
far pointers 50 
manipulating 92 
retrieving 306, 568 
storing, document modes 48 
transfer 384, 438 
transfer mechanism 118 
transferring, list boxes 270 
validating entries 436 
input fields 421, 438, 439 
numeric values only 383 
picture strings 380 
Data data member 
TChooseColorDialog 87 
TChooseFontDialog 89 
TFindReplaceDialog 217 
TOcInitInfo 619 
TOpenSaveDialog 343 
TPrintDialog 368 
TPrinter 370 
data formats 567 
registering 568, 569 
data types 
automation 525, 541, 594 
flags 540 
new types 24 
database tables 
documents as 183 
databases 
registration 529 
validity checking 380 
viewing data 536 
Date data member 
TAutoDate 578 
dates 578 


DC data member 
TChooseFontDialog::TData 
90 
TOcViewPaint structure 652 
TPrintout 375 | 
de.h 20 
Deactivate member function 
TOleWindow 328 
debugclsid registration key 549 
debugdesc registration key 549 
debugger registration key 550 
debugging 
ObjectComponents 
applications 550 
servers 549 
debugprogid registration 
key 550 
decframe.h 20 
declaration specifiers 
_ICLASS macro 535 
_IFUNC macro 535 
_OCFxxxx macros 535 
DECLARE_AUTOCLASS 
macro 551 
DECLARE_COMBASESn 
macros 551 


~ DECLARE RESPONSE_TABLE 


macro 31 
decmdifr.h 20 
decorated windows 11 
DeepCopy data member 
TMenu 293 
default aspect 608 
default error handling 303 
default message processing 
windows 456 
default printers 368, 369 
updating 371 
DefaultProc data member 
TWindow 456 
DefaultProcessing member 
function 
TWindow 460 
DefaultProtocol data member 
TClipboard 93 
DefExt data member 
TOpenSaveDialog::TData 345 
DEFINE_APP_ DICTIONARY 
macro 31 
DEFINE _AUTOAGGREGATE 
macro 552 
DEFINE _AUTOCLASS 
macro 552 
DEFINE_AUTOENUM 
macro 541 


Index 
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DEFINE_COMBASESn 
macros 553 
DEFINE _DOC_TEMPLATE 
_CLASS macro 32 
DEFINE_RESPONSE_TABLE 
macros 32 | 
DefWindowProc member 
function 
TDecoratedMDIFrame 162 
TMDIChild 280 
TMD!{Frame 286 
TOleMDIFrame 322 
TWindow 463. 
delegating to base classes 557 
delegating to other objects 556 
Delete member function 
~— TOcPart 627 
DeleteCondemned member 
function - 
TAppDictionary class 54 
Deleteltem member function 
TControl 118. 
DELETEITEMSTRUCT 
struct 714 
DeleteLine member function 
TEdit 194 
DeleteMenu member function 
TMenu 289 
DeleteSelection member function 
TEdit 194 
DeleteString member function 
TComboBox 103 
TListBox 265 — 
DeleteSubText member function 
TEdit 194 
DeleteTemplate member 
function 
TDocManager 179 
deleting objects 627 
DeltaPos member function 
TScrollBar 392 
dereference operator 584, 585 
description registration key 553 
Destroy member function 
TDialog 165 
-TDocument::List 190 
TMDIChild 280 
TOleFrame 318 
TSortedStringArray 409 
TWindow 463 
Destroy App member function 
TAutoFactory 65 
TOleFactoryBase 316 
DestroyCaret member function 
TWindow 463 


DestroyStashedPopups member | 


function 
TOleFrame 318 
destructors (predefined classes) 
TAutoBase 573 © 
TAutoCommand 574 
TAutoEnumerator 579 
TAutoProxy 587 
TAutoStack 591 
TAutoString 593 
_ TDocument::List 189 
~TOcApp 606 
TOcFormatList 614 
TOcFormatName 617 
TOcModule 623 
TOcNameList 624 
TOcPart 631 
TOcPartCollection 632 
TOleAllocator 653 
TTextGadget class 423 
TUnknown. 659 
TXOle 663 
Detach member function 
TOcFormatList 615 
~TOcNameList 625 
TOcPart 627 
TOcPartCollection 632 
TSortedStringArray 409 
detaching streams 
documents 189 
DetachStream member function 
TDocument 189 


device contexts 


classes 14 
ole client 310 
TDC class 122 
TPrintDC class 356 
device points 310 
DeviceCapabilities member 
function 
TPrintDC class 356 
device-independent bitmap See 
DIB 
DEVMODE struct 716 
dialog boxes 
closing 164, 165 
creating 86, 165 
abort 370, 372 
modeless 388 — 
print setup 368 
CTL3D DLL 163 
executing 165,166 _ 
precautions 305 
file management 201, 213, 
214 
_ files, opening, saving 342 
finding text 216 
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initializing 89, 164, 166, 216 © 
input 255 
interface elements 165 
items 

changing 204 

handles 166 

sending messages to 167 
message constants 46 
messages, processing 165, 

167 

modal 163, 164 
modeless 86, 163, 164, 216 
naming 255 


- dialog control message 


constants 33 
dialog windows 256 
dialog.h 20 
DialogFunction member 
function 
TChooseColorDialog 87 
TChooseFontDialog 89 
TDialog 165 
TFindReplaceDialog 217 
- TOpenSaveDialog 343 
TPrintDialog 369 


_ DIB, array of cels 81 


direction for tiling 424 
directories 
default, registering 554 
documents as disk 183 
paths, registering 561, 571 
directory registration key 554 
DirectoryList member function 
TComboBox 103 
TListBox 265 
DirtyFlag data member 
TDocument 189 
TListView 272 
DirtyLayout data member 
TGadgetWindow 240 
DisableAutoCreate member | 
function 
TWindow 463 
DisableItem member function 
TBitSet 70 
DisableTransfer member 
function 
TWindow 463 


disabling CTL3D DLL 58 


dispatch functions 513-518 

dispatch IDs 592 

Dispatch member function 
TEventHandler 209 
TWindow 463 

dispatch.h 20 

Dispatcher data member 
TResponseTableEntry 388 


dispatching Window 
messages 513 
DispatchScroll member function 
TWindow 491 
displacement 698 
display contexts 
window, painting 478 
displaying current state, 
program 413, 415 
DLGC_BUTTON constant 33 
DLGC_DEFPUSHBUTTON 
constant 33 
DLGC_HASSETSEL constant 33 
DLGC_RADIOBUTTON 
constant 33 
DLGC_STATIC constant 33 
DLGC_UNDEFPUSHBUTTON 
constant 33 
DLGC_WANTALLKEYS 
constant 33 
DLGC_WANTARROWS 
constant 33 
DLGC_WANTCHARS 
constant 33 
DLGC_WANTMESSAGE 
~ constant 33 
DLGC_WANTTAB constant 33 
DLLs 303 
building 49 
error handling 303 
exporting 49 
far pointers 50 
importing 49 
modules 
handles, returning 309 
object-oriented stand- 
in 303 
_OWLDLL 49 
wfAlias and 496 
WIN32, building 50 
dmMDI constant 33 
dmMenu constant 33 
dmNoRevert constant 33 
dmSaveEnable constant 33 
dmSDI constant 33 
dnClose constant 34 
dnCreate constant 34 
Doc data member 
TStream 421 
TView 454 
Doc/ View model 13 
document lists 189 
registering documents 683 
docfilter registration key 554 
docflags registration key 554 


DoChangeCBChain member 
function 
TClipboardViewer 97 
DOCINEFO struct 
TPrintDC 363 
DocList data member 
TDocManager 177 
docmanag.h 20 
DoCommand member function 
TTinyCaption 426 
docprint aspect 608 
DoCreate member function 
TCommonDialog 113 
TDialog 165 
TFindDialog 216 
TFindReplaceDialog 217 
TReplaceDialog 388 
DocTitleIndex data member 
TFrameWindow 225 
doctpl.h 20 
document manager 176 
documents 182 
closing 34 
creating 34, 679 
files as 183 
interfaces 451 
lists 189 
manager mode constants 33 
message constants 34 
naming 453 
open modes 48 
paths, specifying 212 
property attributes 48 
sharing modes 51 
string ID constants 42 
template constants 34 
templates, creating 32 
viewing 451, 498 
docview.h 20 
DoDestroy member function 
TClipboardViewer 97 
DoDrawClipboard member 
function 
TClipboardViewer 97 
DoExecute member function 
TChooseColorDialog 87 
TChooseFontDialog 89 
TCommonDialog 113 
TDialog 165 
TFileOpenDialog 214 
TFileSaveDialog 214 
TOpenSaveDialog 344 
TPrintDialog 368 
DoLButtonUp member function 
TTinyCaption 426 


DoMouseMove member 
function 
TTinyCaption 426 | 
DoNCActivate member function 
TTinyCaption 427 
DoNCCalcSize member function 
TTinyCaption 427 
DoNCHitTest member function 
TFloatingFrame 220 
TTinyCaption 427 
DoNCLButtonDown member 
function 
TTinyCaption 427 
DoNCPaint member function 
TTinyCaption 427 
DoSearch member function 
TEditSearch 205 
DoSysCommand member 
function 
TTinyCaption 427 
DoSysMenu member function 
TTinyCaption 427 
double far*() operator 
TAutoVal 596 
double types 578 
double() operator 
TAutoDate 578 
TAutoVal 596 
DoVerb member function 
TOcPart 627 
DownHit data member 
TTinyCaption 425 
DPtoLP member function 
TDC 124 
drag and drop 613, 618 
events 566 
filenames 685 
Drag member function 
TOcApp 602 
TVbxControl 442 
DragAcceptFiles member 
function 
TWindow 464 
DragDC data member 
TOleWindow 329 
DragFinish member function 
TDropInfo 685 
dragging objects 602 
DragHit data member 
TOleWindow 329 
DragPart data member 
TOleWindow 329 
DragPt data member 
TOleWindow 329 
DragQueryFile member function 
TDropInfo 685 
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DragQueryFileCount member 
function 
TDropInfo 685 
DragQueryFileNameLen 
member function 
TDropInfo 686 
DragQueryPoint member 
~ function 
TDropInfo 686 
DragRect data member 
TOleWindow 329 
DragStart data member 
TOleWindow 329 
Draw member function 
TOcPart 627 
DrawFocusRect member 
function 
TDC 124 
Drawlcon member function 
TDC 125 
drawing controls 118, 119 
drawing gauges 245 
drawing objects 432, 566 
DrawlItem member function 
TControl 118 
TMenu 289 
DRAWITEM message 118 
DRAWITEMSTRUCT struct 719 
Draw MenuBar member function 
| TWindow 464 | 
DrawText member function 
TDC 125 
dtAutoDelete constant 34 
dtAutoOpen constant 34 
dtCreatePrompt constant 34 
dtDynRegInfo constant 34 
dtFileMustExist constant 34 
dtHidden constant 34 
dtHideReadOnly constant 34 
dtNewDoc constant 34 | 
dtNoAutoView constant 34 
dtNoReadOnly constant 34 
dtNoTestCreate constant 34 
dtOverwritePrompt constant 35 
dtPathMustExist constant 35 
dtProhibited constant 35 
dtReadOnly constant 35 
dtRegisterExt constant 35 
dtSelected constant 35 
dtSingleUse constant 35 
dtSingleView constant 35 
dual DC synchronizing 
functions 376, 379 
DynamicCast function 555 
dynamic-link libraries See DLLs 


E 


edge constraints 190, 258, 261 


edit constants 29 
edit controls 192, 204 
attributes, setting 193, 197 
closing 198 
first visible line 194 
formatting rectangle 195, 197 
handles 197 
data 194 
interface elements 192 
notification codes 200 
passwords 195, 197 
registration class name 200 
tab stop positions 197 
text 
clearing 199 
copying 193, 199 
cutting 194, 199 
deleting 194, 199 
lines 194 
getting 194, 196 
inserting 196 
limiting 201 
line index 195 
line length 195 
modified 196 
number of lines 195 
pasting 196, 199 
position 192, 195 
scrolling 196 
selected, getting 195 
selecting 197 
undoing 199 
undoing 193, 194, 198 
word break 198 
wordwrapped lines 194, 196 
edit file constants 29 
edit file ID constants 43 
Edit menu, automated objects 
and 600, 603 
edit message constants 35 
edit replace constants 30 
edit view constants 30 
edit view ID constants 42 
edith 21 
editfile.h 21 
editing objects 639 
editing windows 
control attributes 193 
editsear.h 21 
editview.h 21 
Ellipse member function 
TDC 126 
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Embedded data member 


_ TDocument 189 
TOleWindow 329 


embedded objects 


activating 626, 630, 646 
container classes 626, 645 
copying 638, 646 
deleting 627 
editing 639 
executing verbs 627 
loading 566, 611, 629, 639 
painting 566, 627, 638, 648, 
651 
pasting 646, 648 
presentation aspects 566, 
569, 608 | 
saving 566, 611, 612, 630, 639 
server classes 637 
embedding ObjectComponents 
classes 530 
embedding ObjectComponents 
enums 532 
embedding ObjectComponents 
messages 532 


embedding ObjectComponents 


structs 532 
EmptyClipboard member 
function 
TClipboard 93 
EmptyUndoBuffer member 
function 
TEdit 194. 
EN_CHANGE constant 35 
EN_ERRSPACE constant 35, 200 
EN_HSCROLL constant 35 
EN_KILLFOCUS constant 35 
EN_MAXTEXT constant 36 
EN_SETFOCUS constant 36 
EN_UPDATE constant 36 
EN_VSCHOLL constant 36 
enable 3-D support 166 
Enable member function 
TButtonGadgetEnabler 80 
TCommandEnabler 111 
TMenultemEnabler 299 
EnableAutoCreate member 
function 
TWindow 464 
EnableBWCC member function 
TApplication 58 
EnableCtl3d member function 
TApplication 58 | 
EnableCtl3dAutosubclass 
member function 
TApplication 58 


EnableEditMenu member 
function 
TOcApp 603 
EnableItem member function 
TBitSet 70 
EnableKBHandler member 
function 
TFrameWindow 223 
EnableMenultem member 
function 
TMenu 289 
EnableScrollBar member 
function 
TWindow 155, 464 
EnableTinyCaption member 
function 
TTinyCaption 427 
EnableTransfer member function 
TWindow 464 
EnableWindow member 
function 
TMD!IChild 280 
TWindow 464 
encapsulated functions 
WIN API 701, 707 
Windows API Clipboard 92 
END_AUTOAGGREGATE 
macro 555 | 
END_AUTOCLASS macro 555 
END_AUTOENUM macro 541 
END_REGISTRATION_ macro 6 
75 
END_RESPONSE_TABLE 
macro 35 
EndDoc member function 
TPrintDC 359 
EndDocument member function 
TPrintout 373 
EndModal member function 
TApplication 58 
end-of-line characters 194 
EndPage member function 
TPrintDC 359 
EndPath member function 
TDC 126 
EndPrinting member function 
TPrintout 373 
EndView member function 
TScroller 397 
ENErrSpace member function 
TEdit 200 
Entry data member 
TEventHandler::TEventInfo 
210 
enumerations 
automated objects 579, 581 


exception status 56 
EnumFontFamilies member 

function 

TDC 126 
EnumFonts member function 

TDC 126 
EnumMetaFile member function 

TDC 127 
EnumObjects member function 

TDC 127 
EnumProps member function 

TWindow 464 
enums 

TOcDropAction 613 

TOcInitHow 618 

TOcInitWhere 621 

TOcInvalidate 621 

TOcPartName 634 

TOcScrollDir 642 
EnumVerbs member function 

TOcPart 627 
error codes 90 

automation servers 546 

dialog boxes 88, 218, 364 

files 345 

OLE 562, 663 

printing 370 
Error data member 

TChooseColorDialog::TData 

87 
TChooseFontDialog::TData 90 
TFindReplaceDialog::TData 

218 

TOpenSaveDialog::TData 345 

TPrintDialog::TData 364 

TPrinter 370 
Error member function 

TFilterValidator 215 

TModule 305 

TPXPictureValidator 381 

TRangeValidator 383 

TStringLookupValidator 422 

TValidator 437 
error messages 

displaying 305 

maximum number of 

characters 46 

error strings 46 
ErrorCode data member 

TxXAuto 661 . 

TXObjComp 662 | 
errors, default handing 303 
Escape member function 

TPrintDC 359 
EV_CHILD_ NOTIFY macro 36 
EV_CHILD_NOTIFY_ALL 

_CODES macro 36 


EV_CHILD_ NOTIFY _AND 
_CODE macro 36 
EV_COMMAND macro 36 
EV_COMMAND_ AND _ID 
macro 36 
EV_COMMAND_ENABLE 
macro 36 
EV_MESSAGE macro 36, 321 
EV_NOTIFY_AT_ CHILD 
macro 36 
EV_OC_APPBORDERSPACE- 
REO macro 321 
EV_OC_APPBORDERSPACE- 
SET macro 321 
EV_OC_APPFRAMERECT 
macro 321 
EV_OC_APPINSMENUS 
macro 321, 323 
EV_OC_APPMENUS macro 321 
EV_OC_APPRESTOREUI 
macro 321 
EV_OC_APPROCESSMSG 
macro 321 
EV_OC_APPSHUTDOWN 
macro 321 
EV_OC_APPSTATUSTEXT 
macro 321 
EV_OC_VIEWATTACH- 
WINDOW macro 326 
EV_OC_VIEWCLOSE 
macro 326 
EV_OC_VIEWINSMENUS 
macro 326 
EV_OC_VIEWLOADPART 
macro 326 
EV_OC_VIEWOPENDOC 
macro 326 
EV_OC_VIEWSAVEPART | 
macro 326 
EV_OWLDOCUMENT 
macro 36 
EV_OWLNOTIFY macro 36 
EV_OWLVIEW macro 36 
EV_REGISTERED macro 36 
EV_WM_ACTIVATEAPP 
macro 321, 323 
EV_WM._ SIZE macro 321 
EvActivate member function 
TOcApp 603 
TOcView 646 
EvActivateApp member 
function 
TOleFrame 318 
TOleMDIFrame 322 
EvCanClose member function 
TDocManager 179 
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EvChangeCBChain member 
function 
TClipboardViewer 98 
EvChar member function 
TEdit 200 
EvChildInvalid member function 
TWindow 464 
EvClose member function 
TCommonDialog 114 
TDialog 165 
TOcRemView 638 
TOcView 647 
EvClose message 165 
EvCommand member function 
TDecoratedFrame 161 
TFrameWindow 226 
TOleWindow 333 
TPrinterAbortDlg 372 — 
TTinyCaption 428 
TWindow 465 
EvCommandEnable member 
function 
TDecoratedFrame 161 
TFrameWindow 226 
TOleWindow 333 
TWindow 465 
EvCompareltem member 
function 
TControl 118 
EvCtlColor member function 
TDialog 165 
EvCtlColor message 166 
EvDeleteltem member function 
TControl 118 
_EvDestroy member function 
TClipboardViewer 98 
EvDoVerb member function 
TOleWindow 334 
EvDrawClipboard member 
function 
TClipboardViewer 98 
EvDrawltem member function 
TControl 119 
event handlers 447, 565 
event handling 31, 36. 
finding events 209 
response table entries 208 
event IDs 504 
event messages 
ObjectComponents 565 
EvEnterIdle member function — 
TDecoratedFrame 161 
eventhan.h 21 
events 
non-client 424 
views 183 


| EvEraseBkgnd ee member 


TGauge 245 
EvEraseBkgnd member function 
_ TFrameWindow 226 — 
TSlider 401 
EvFindMsg member function 
TEditSearch 205 
EvGetDlgCode member function 
TButton. 73 
TCheckBox 85 
TEdit 200 
TListView 275 
TSlider 401 
EvHScroll member function 
TScrollBar 392 
EvInitDialog member function 
TDialog 166 
EvInitMenuPopup member 
function — 
TFrameWindow 226 
EvKeyDown member function 
TEdit 200 
TSlider 401 
EvkillFocus member function 
TEdit 200 
TSlider 401 
EvLButtonDbIClk member 
function 
TOleWindow 334 
TSlider 402 
EvLButtonDown member 
function 
TGadgetWindow 241 
TOleWindow 334 
TSlider 402 


_ EvLButtonUp member function — 


TGadgetWindow 241 
TSlider 402 
TTinyCaption. 428 
EvMDIActivate member 
function 
TMD!IChild 280 
TOleWindow 334 
EvMD!ICreate member function 
TMD!IClient 284 
EvMD Destroy member function 
TMD!IClient 284 
EvMeasureltem member 
function 
TControl 119 
EvMenuSelect member function 
_ TDecoratedFrame 161 
EvMouseMove member function 
TGadgetWindow 241 
~ TOleWindow 334 
TSlider 402 . 
TTinyCaption 428 
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EvNC Activate member function 
TMDIChild 280 
TTinyCaption 428 

EvNCCalcSize member function 
TTinyCaption 428 | 

EvNCDestroy member function — 
TEditView 207 | 
TFindReplaceDialog 217 

EvNCHitTest member function 
TTinyCaption 428 

EvNCLButtonDown member 

function 
TTinyCaption 429 

EvOcApp member function 
TOleFrame 320 

EvOcAppBorderSpaceReq 

member function 
TOleFrame 318 
EvOcAppBorderSpaceSet 
member function 
TOleFrame 318 
EvOcAppDialogHelp member 
function 
TOleFrame 319 
EvOcAppFrameRect member 
function 
TOleFrame 319 
EvOcAppInsMenus member 
function 
TOleFrame 319 
TOleMDIFrame 322 
EvOcAppProcessMsg member 
function 
_ TOleFrame 319 
EvOcAppRestoreUI member 
function — 
TOleFrame 319 
EvOcAppShutdown member 
function 
TOleFrame 319 
EvOcAppStatusText member 
function 
TOleFrame 319 


~EvOcEvent member function 


TOleFrame 319 
TOleWindow 334 
EvOcPartInvalid member 
function 
TOleWindow 335 
EvOcViewAttachWindow 
member function 
TOleView class 325 
TOleWindow 335 
EvOcView BorderSpaceReq 
member function 
TOleWindow 335 


EvOcViewBorderSpaceSet 
member function 
TOleWindow 335 
EvOcViewClipData member 
function 
TOleWindow 335 
EvOcViewClose member 
function 
TOleView class 325 
TOleWindow 335 
EvOcViewDrag member 
function 
TOleWindow 335 
EvOcViewDrop member 
function 
TOleWindow 336 
EvOcViewGetPalette member 
function 
TOleWindow 336 
EvOcViewGetScale member 
function 
TOleWindow 336 
EvOcViewGetSiteRect member 
function 
TOleWindow 336 
EvOcViewInsMenus member 
function 
TOleView class 325 
TOleWindow 336 
EvOcViewLoadPart member 
function | 
TOleView class 325 
TOleWindow 336 
EvOcViewOpenDoc member 
function 
TOleView class 325 
TOleWindow 336 
EvOcViewPaint member 
function 
TOleWindow 337 
EvOcViewPartInvalid member 
function 
TOleView class 325 
TOleWindow 337 
EvOcViewPartSize member 
function 
TOleWindow 337 
EvOcViewSavePart member 
function 7 
TOleView class 32 
TOleWindow 337 
EvOcViewScroll member 
function 
TOleWindow 337 


EvOcViewSetScale member 
function 
TOleWindow 337 
EvOcViewSetSiteRect member 
function 
TOleWindow 338 
EvOcViewShow Tools member 
function 
TOleWindow 338 


EvOcView Title member function 


TOleWindow 338 
EvPaint member function 
TControl 119 
TDialog 166 
TFrameWindow 226 
TSlider 402 
TTinyCaption 429 
EvParentNotify member 
function 
TFrameWindow 227 
EvPreProcessMenu member 
function 
TDocManager 179 
EvQueryDragIcon member 
function 
TFrameWindow 227 
EvRButtonDown member 
function 
TOleWindow 338 
EvRButtonUp member function 
TOleWindow 334 
EvResize member function 
TOcApp 603 
TOcView 647 
EvSetCursor member function 
TOleWindow 338 
EvSetFocus member function 
TFrameWindow 227 
TOcApp 603 
TOcView 647 
TOleWindow 339 
TSlider 402 
EvSetFont member function 
TDialog 166 
EvSetRGBColor member 
function 
TChooseColorDialog 87 
EvSize member function 
TDecoratedFrame 161 
TFrameWindow 227 
TGadgetWindow 241 
TLayoutWindow 264 
TOleFrame 320 
TOleWindow 339 
TPreviewPage 355 
TSlider 402 
TStatic 412 


EvSyscolorChange member 
function 
TGadgetWindow 241 
EvSysCommand member 
function 
TTinyCaption 429 
TWindow 465 
EvTimer member function 
TOleFrame 320 
EvVbxDispatch member 
function 
TVbxEventHandler 451 
EvVScroll member function 
TScrollBar 392 


EvWakeUp member function 


TDocManager 179 
except.h 21 
exception bit flags 56 
exception classes 
ObjectComponents 523 
TXAuto 660 
TXObjComp 661 
TXOle 662 
TXRegistry 664 
exception handler 
precautions 305 
exception handling 
TStatus 412 
TWindow 456 
exception objects 
copying 
TXBase class 700 


TXCompatibility class 500 


TXGdi class 250 


TXInvalidMainWindow 


class 63 

TXInvalidModule 
class 310 

TXMenu class 501 

~ TXOutOfMemory 

class 501 

TXOw1l class 504 

TXWindow class 499 

throwing 
TXBase class 700 


TXCompatibility class 500 


TXGdi class 250 


TXInvalidMainWindow 


class 63 
TXInvalidModule 
class 310 
TXMenu class 501 
TXOutOfMemory 
class 502 
TXOwl class 504 
TXWindow class 500 
exception status enum. 56 
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exceptions 250 
error strings 46 
message constants 43 
TXBase class 699 
TXCOMPATIBILITY 304 
TXCompatibility class 500 
TXInvalidMainWindow 62 
TXInvalidModule 307 
TXInvalidModule class 310 
TXInvalidWindow class 63 
TXOutOfMemory class 501 
TXOw!l class 502 
TXPrinter class 372 
TXValidator class 440 
TXWindow class 499 
using catch keyword 502 
using try keyword 502 
exception-unsafe code 479 
ExcludeClipRect member 
function 
7 TDE€ 127 
ExcludeUpdateRgn member 
function 
TDC 128 
ExecDialog member function 
TModule 305 
ExecPrintDialog member 
function. 
TPrinter 371 
Execute member function 
TAutoCommand. 575 
TDialog 166 
executing object verbs 627 
_export keyword 49, 50 
EXPOSE_APPLICATION 
macro 556 
EXPOSE_DELEGATE 
macros 556 
EXPOSE INHERIT macros 557 
EXPOSE_ITERATOR | 
macros 557 
EXPOSE_METHOD macros 558 
EXPOSE_PROPxxxx macros 559 
EXPOSE_QUIT macro 560 
ExStyle data member 
TWindowAttr 495 
extension registration key 560 
Extent data member 
TMetaFilePict 303 
TOcView 650 
ExtFlood Fill member function 
TDC 128 
-ExtractGroups member function 
TMenuDesc 298 
ExtTextOut member function 
TDC 128 


F 


factory object creation 39 
factory template classes 36 
factory template hierarchy 37 
Fail member function 
TAutoCommand 575 
FARPROC() operator 
TProcinstance 690 
_fastthis keyword 50 


_ FHdl data member 


TFileDocument 213 
file buffers 210 
file constants 40 
file errors 213 
file formats, registering 561 
file handles 213 


file matching patterns 180 


file names 
drag and drop 685 
filter, copying 346 
returning expanded 306, 310 
File Open common dialog box 
default directories 554 
default file-name 
extensions 560 
listing files 554 
FileData data member 
TEditFile 202 
filedoc.h 21 
filefmt registration key 561 
FileName data member 
TEditFile 202 
TOpenSaveDialog::TData 345 
file-name extensions | 
registering 560 
files 
attributes 343 
compound 
loading and saving 609 
control IDs 40 
ID constants 43 
INI 379 
initialization 379 
listing 554 
managing 201, 213, 214 
opening 213, 342. 
document modes 48 
profile 379 
returning information on 43 
saving 214, 342 
sharing modes 51 
viewing 210 
FillPath member function 
TDC 129 
FillRect member function 
TDC 129 
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FillRgn member function 
TDC 129 

Filter data member 
-TOpenSaveDialog::TData 345 

filter validators 215 | 


- FilterIndex data member 


TOpenSaveDialog::TData 345 
Find member function 
TApplication 58 
TEventHandler 209 
TOcFormatList 615 
TOcNameList 625 
TOcPartCollection 632 
TSortedStringArray 409 
find-and-replace attributes 216, 
217 
FindChildMenu member 
function 
TMD {IFrame 285 
FindColor member function 
TDib 171 


~ FindDocument member function 


TDocManager 180 

FindExactString member 

function 

TListBox 266 

FindIndex member function 
TDib 171 

FindProperty member function 
TDocument 185 
TFileDocument 212 
TStorageDocument 418 
TView 452 | 

findrepLh 21 _ 

FindResource member function 
TModule 305 

FindString member function 
TComboBox 103 
TListBox 266 

FindWhat data member 
TFindReplaceDialog: ‘TData 

219 

FirstBand data member 
TPrinter 370 

FirstGadget member function 
TGadgetWindow 237 

FirstThat member function 
TSortedStringArray 409 — 
TWindow 466 

FirstThat typedef 114 

flags 496 
automation data types 540 
automation servers 541 
automation symbol flags 546 
changing 605, 655, 657 
dialog boxes 88 
document view option 554 


files 345 
interface objects setting 483 
objects 
aspect 536 
verbs 570 
OLE running modes 607 
setting and clearing 69 
testing 577, 604 
Flags data member 
TChooseColorDialog::TData 
88 
TChooseFontDialog::TData 
90 
TFindReplaceDialog::TData 
219 
TOpenSaveDialog::TData 345 
TPrintDialog::TData 365 
TPrinter 371 
Flags member function 
TColor 100 
FlashWindow member function 
TWindow 466 
FlattenPath member function 
TDC 129 
float far*() operator 
TAutoVal 596 
float types 580 
float() operator 
TAutoVal 596 
floatfra.h 21 
FloodFill member function 
TDC 129 
Flush member function 
TSortedStringArray 409 
FlushDoc member function 
TDocManager 180 
focus, shifting 118, 119 
Font data member 
TGadgetWindow 240 
FONTENUMPROC 126 
fonts 
caption bars 425 
changing 166 
creating point size 234 
for gadget windows 234 
system 258 
FontType data member 
~ TChooseFontDialog::TData 
91 
ForceAl/Bands data member 
TPrintout 375 
ForEach member function 
TSortedStringArray 409 
TWindow 466 
FormatLines member function 
TEdit 194 


FormatList data member 
TOcView 650 

formatn registration key 561 

formats 567 | 
file, registering 561 
registering 568, 569 

ForwardEvent member function 
TOcApp 606, 607 
TOcView 649 

ForwardMessage member 

function 

TWindow 467 

fr data member 
TFindReplaceDialog 217 

Frame data member 
TTinyCaption 426 

FrameRect member function 
TDC 130 

FrameRgn member function 
TDC 130 

framewin.h 21 

Free member function 
TOleAllocator 653 

friend functions 
TResId class 697 

FromPage data member 
TPrintDialog::TData 366 

functions 
dispatch 513-518 
message dispatcher 52 
transfer 432 


G 


gadget data member 
TButtonGadgetEnabler 80 
gadget placement 353 
gadget settings 
hint mode 236 
tiling 424 
gadget.h 21 
GadgetChangedSize member 
function 
TGadgetWindow 237 
GadgetFromPoint member 
function 
TGadgetWindow 237 
GadgetReleaseCapture member 
function 
TGadgetWindow 237 
gadgets 12, 228 
border locations 229 
border styles 229 
creating separators 398 
margins 230 
setting attributes 236 
TGadgetWindow objects 236 


Gadgets data member 
TGadgetWindow 240 
GadgetSetCapture member 
function 
TGadgetWindow 237 
gadgetwi.h 21 
gauge controls 243 
gauge.h 21 
GDI classes 245 
GDI message constants 44 
GDI objects 14 
gdibase.h 21 
ediobjec.h 21 
geometry.h 21 
GetActiveMDIChild member 
function 
TMD!IClient 282 
GetActivePart member function 
TOcView 647, 650 
GetActiveView member function 
TOcDocument 610 
GetActiveWindow member 
function 
TWindow 467 
GetAppDescriptor member 
function 
TOcRegistrar 636 
GetApplication member function 
TAppDictionary class 54 
TDocManager 180 
TWindow 467 
GetApplicationObject member 
function 
TApplication 40 
GetAspectRatioFilter member 
function 
TDC 130 
GetAttributeHDC data member 
TPrintPreviewDC 379 
GetAttributeHDC member 
function 
TDC 159 
GetBitmapBits member function 
TBitmap 66 
GetBitmapDimension member 
function 
TBitmap 66 
GetBits member function 
TDib 171 
GetBkColor member function 
TDC 130 
TSlider 402 
GetBkMode member function 
TDC 130 
GetBorders member function 
TGadget 230 
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GetBorderStyle member function 
TGadget 230 
GetBoundingRect member 
function 
TUIHandle 435 
GetBounds member function 
TGadget 230 | 
GetBoundsRect member 
function 
TDC 130 
GetBrushOrg member function 
~ TDC 131 
GetBWCCModule member 
function 
TApplication 59 
. GetCaptionRect member 
function 
TTinyCaption 429 
GetCapture member function 
TWindow 467 a 
GetCaretBlinkTime member 
function 
TWindow 467 
GetCaretIndex member function 
TListBox 266 
GetCaretPos member function 
TWindow 467 
GetCharABCWidths member 
function 
TDC 131 
GetCharWidth member function 
TDC 131 
GetCheck member function 
TCheckBox 84 
GetChildLayoutMetrics member 
function 
TLayoutWindow 263 
~ GetClassInfo member function 
TModule 306 
GetClassLong member function 
TWindow 468 
GetClassName member function 
TButton 74 
TCheckBox 85 
TComboBox 106 
TDialog 167 
TEdit 200 
TGroupBox 251 
TListBox 270 
TMD!]Client 284 
TRadioButton 383 
TScrollBar 394 
TStatic 412 
TVbxControl 446 
TWindow 491 
GetClassWord member function 
TWindow 468 


GetClientHandle member 
function 
TModule 306 
GetClientRect member function 
TWindow 468 
GetClientWindow member 
function 
TFrameWindow 223 
TMD]IFrame 286 
GetClipboard member function 
TClipboard 94 
GetClipboardData member 
function 
TClipboard 94 
GetClipboardFormatName 
member function 
' TClipboard 94 
GetClipboardOwner member 
function | 
TClipboard 94 
GetClipboardViewer member 
function 
TClipboard 94 
GetClipBox member function 
TDC 131 
GetClipRen member function 
TDC 131 : 
GetColor member function - 
TDib 171 
GetColors member function 
TDib 171 
GetCommandTarget member 
function 
TFrameWindow 223 
TMDI{IFrame 286 
GetContainerTitle member 
function 
TOcRemView 638 


GetCount member function 


TComboBox 103 
TListBox 266 
GetCtl3dModule member 
function 
TApplication 59 
GetCurrentDoc member function 
TDocManager 180 
GetCurrentObject member 
function 
TDC 132 


~ GetCurrentPosition member 


function 
TDC 132 
GetCursorld member function . 
TUIHandle 435 
GetCursorPos member function 
TWindow 468 
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GetDataType member function 
TAutoVal 596 


~GetDCOrg member function 


TDC 132 
GetDefaultExt member function 
TDocTemplate 680 
GetDefaultId member function 
TDialog 166 
GetDefaultPrinter member 
function 
TPrintDialog 368 
TPrinter 371 
GetDescription member function 
TDocTemplate 680 . 
GetDesiredSize member function 
TBitmapGadget 69 
TButtonGadget 78 
TControlGadget 116 
TGadget 230 
TGadgetWindow 241 
TMessageBar 300 
TTextGadget 423 
TToolBox 431 
GetDesktopWindow member 
function 
TWindow 469 
GetDeviceCaps member 
function 
TDC 132 | 
TPrintPreviewDC 376 
GetDeviceName member 
function 
TPrintDialog::TData 367 
GetDevMode member function 
TPrintDialog::TData 367 
GetDevNames member function 
TPrintDialog::TData 367 
GetDialogInfo member function 
TPrintout 374 
GetDIBits member function 
TDC 132 
GetDirection member function 
TGadgetWindow 237, 239 
GetDirectory member function 
TDocTemplate 680 
GetDlgCtrlID member function 
TWindow 469 
GetDlgItem member function 
TWindow 469 
GetDlgItemInt member function 
TWindow 469 
GetDlgltemText member 


- function 


TWindow 469 
GetDocManager member 
function 
TApplication 59 


TDocTemplate 681 
TDocument 185 
GetDocPath member function 
TDocument 185 
GetDocument member function 
TStream 420 
TView 452 
GetDriverName member 
function 
TPrintDialog::TData 367 
GetDroppedControlRect 
member function 
TComboBox 103 
GetDroppedState member 
function 
TComboBox 103 
GetEditSel member function 
TComboBox 103 
GetEnabled member function 
TGadget 231 
GetErrorCode member function 
TXOwl 504 
GetEventIndex member function 
TVbxControl 442 
GetEventName member 
function 
TVbxControl 442 
GetExtendedUI member 
function 
TComboBox 103 
GetFactory member function 
TOcRegistrar 636 
GetFileFilter member function 
TDocTemplate 681 
GetFileTitle member function 
TOpenSaveDialog 342 
GetFileTitleLen member function 
TOpenSaveDialog 342 
GetFirstChild member function 
TWindow 469 
GetFirstVisibleLine member 
function 
TEdit 194 
GetFlags member function 
TDocTemplate 681 
GetFocus member function 
TWindow 469 
GetFont member function 
TGadgetWindow 237 
GetFontData member function © 
TDC 133 
GetFontHeight member function 
TGadgetWindow 237, 240 
GetGlyphDib member function 
TButtonGadget 78 


GetGlyphOutline member 
function 
TDC 133 
GetGroupCount member 
function 
TMenuDescr 297 
GetHandle member function 
TEdit 194 
TMenu 289 
TMenuDescr 296 
GetHandled member function 
TCommandEnabler 112 
GetHCTL member function 
TVbxControl 442 
GetHDC member function 
TDC 159 
GetHintMode member function 
TGadgetWindow 237 
GetHorizontalExtent member 
function 
TListBox 266 
GetHWndState member function 
TWindow 469 
GetIconInfo member function 
TCursor 121 
TIcon 255 
GetId member function 
TGadget 231 
TMenuDescr 297 
TOcFormatName 617 
— TWindow 469 
GetIndex member function 
TDib 171 
GetIndices member function 
TDib 171 
GetInfo member function 
TDib 172 
GetInfoHeader member function 
TDib 172 
GetInitialRect member function 
TOcRemView 638 
GetInnerRect member function 
TControlGadget 116 
TGadget 233 
TGadgetWindow 241 
TMessageBar 300 
GetInsertPosition member 
function 
TOleWindow 339 


~ GetInstance member function 


TModule 306 
GetInstanceData member 
function 
TModule 306 
GetInt member function 
Profile class 380 


GetltemData member function 
TComboBox 104 
TListBox 266 
GetItemDatas member function 
TComboBoxData 107 
TListBoxData 271 
GetItemHandle member 
function 
TDialog, obsolete 166 
GetltemHeight member function 
TComboBox 104 
TListBox 266 
GetItemRect member function 
TListBox 266 
GetItemsInContainer member 
function 
TSortedStringArray 409 
GetKerning Pairs member 
function 
TDC 133 
GetLastActivePopup member 
function 
TWindow 470 
GetLastChild member function 
TWindow 470 
GetLine member function 
TEdit 194 
GetLineFromPos member 
function 
TEdit 195 
GetLineIndex member function 
TEdit 195 
GetLineLength member function 
TEdit 195 
GetLogPerUnit member function 
TOleWindow 339 
GetMainWindow member 
function 
TApplication 59 
GetMapMode member function 
TDC 133 
GetMargins member function 
TGadget 231 
TGadgetWindow 242 
GetMaxBoxRect member 
function 
TTinyCaption 429 
GetMenu member function 
TMenultemEnabler 299 
TWindow 470 
GetMenuCheckMark- 
Dimensions member function 
TMenu 290 
GetMenuDescr member function 
TFrameWindow 224 
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GetMenultemCount member 
function | 
TMenu 290 
GetMenultemID member 
function 
TMenu 290 
GetMenuState member function 
~ TMenu 290 
GetMenuString member 
function 
TMenu 290° 
GetMetaFileBits member 
function 
TMetaFilePict 302 
GetMetaFileBitsEx member 
function 
TMetaFilePict 302 
GetMinBoxRect member 
function 
TTinyCaption 429 
GetModelndicator member 
function 
TStatusBar 414 
GetModule member function 
TDocTemplate 681 
TMenuDescr 297 
TWindow 470 
GetModuleFileName member 
function 
TModule 306, 310 
GetModuleUsage member 
function 
TModule 307 
GetName member function 
TModule 307 
TOcApp 603 
TOcDocument 610 
TOcFormatName 617 
TOcPart 628 
GetNameLen member function 
TOcPart 628 
GetNameList member function 
TOcApp 603 
GetNearestColor member 
function 
TDC 134 
GetNearestPaletteIndex member 
function 
TPalette 348 
GetNewStorage member 
function — 
TOleDocument 312 
GetNextDlgGroupItem member 
function 
TWindow 470 


GetNextDlgTabItem member 
function | 
TWindow 470 
GetNextTemplate member 
function 
TDocManager 180 
TDocTemplate 681 
GetNextViewId member 
function 
TView 452 


~ GetNextWindow member 


function 
TWindow 470 
GetNumEntries member 
function 
TPalette 349 
GetNumEvents member 
function a 
TVbxControl 442 | 
GetNumLines member function 
TEdit 195 
GetNumProps member function 
TVbxControl 442 
GetObject member function 
TBitmap 67 
TBrush 72 
TFont 222 
—TGdiObject 246 
TPalette 349 
TPen 352 
GetOcApp member function 
TOleDocument 312 . 
TOleFrame 317 
TOleWindow 328 
GetOcDoc member function 
TOleDocument 312 
TOleWindow 328 


~ GetOcDocument member 


function 
TOcView 647 
GetOcRemView member 
function 
TOleWindow 328 
GetOcView member function 
TOleWindow 328 
GetOpenClipboardWindow 
member function 
TClipboard 95 
GetOpenMode member function 
TDocument 185 
TStream 420: 
GetOptions member function 
TRegistrar 655 
GetOrigin member function 
TOcView 647 
GetOuter member function 
TUnknown 658 . 
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GetOuterSizes member function 
TGadget 231 
GetOutlineTextMetrics member 
function 
TDC 134 


_ GetOutputName member 


function 
TPrintDialog::TData 367 
GetPaletteEntries member | 
function | 
TPalette 349 
GetPaletteEntry member 
function 
TPalette 349 
GetParent member function 
TWindow 471 
GetParentDoc member function 
TDocument 185 
GetParentObject member 
function 
TModule 307 
GetParts member function 
TOcDocument 611 
GetPasswordChar member 
function 
TEdit 195 
GetPixel member function 
TDC 135 | 
GetPolyFillMode member 
function | 
TDC 135 
GetPos member function 
TOcPart 628 
GetPosition member function 
TMenultemEnabler 299 
TScrollBarData 392 
TSlider 400 
GetPriorityClipboardFormat 
member function 
TClipboard 95 
GetProcAddress member 
function 
TModule 307 
GetProp member function 
TVbxControl 442 
TWindow 471 


GetProperty member function 


TDocument 185 
_ TFileDocument 212 
TStorageDocument 418 
TView 452 
GetPropIndex member function 
TVbxControl 443 


_GetPropName member function 


TVbxControl 444 


GetPropType member function 
TVbxControl 444 
GetRange member function 
TGauge 243 
TScrollBar 392 
TSlider 400 
GetRect member function 
TEdit 195 
TOcPart 628 
GetRefCount member function 
TUnknown 659 
GetRegistrar member function 
TOcApp 604 
TOcModule 623 
GetRegList member function 
TDocTemplate 681 
GetRemViewBucket member 
function 
TOleFrame 317 
GetResultName member 
function 
TOcFormatName 617 
GetRgnBox member function 
TRegion 385 7 
GetROP2 member function 
TDC 135 
GetScale member function 
TOcScaleFactor 642 
GetScaleFactor member function 
TOcScaleFactor 642 
GetScrollPos member function 
TWindow 471 
GetScrollRange member function 
TWindow 471 
GetSel member function 
TListBox 267 
GetSelCount member function 
TComboBoxData 107 
TListBox 267 
GetSelection member function 
TComboBoxData 107 
TEdit 195 
GetSelIndex member function 
TComboBox 104 
TComboBoxData 107 
TListBox 267 
GetSelIndexes member function 
TListBox 267 
GetSelIndices member function 
TListBoxData 271 
GetSelString member function 
TComboBoxData 107 
TListBox 267 
TListBoxData 271 


GetSelStringLength member 
function 
TComboBoxData 107 
TListBoxData 271 
GetSelStrings member function 
TListBox 267 
GetServerName member 
function 
TOcPart 628 
GetSetup member function 
TPrinter 369 
GetSize member function 
TOcPart 628 
GetState member function 
TCheckBox 84 
GetStorage member function 
TOcDocument 611 
TStorageDocument 418 
GetStreamName member 
function 
TStream 421 
GetStretchBltMode member 
function 
TDC 135 
GetString member function 
TComboBox 104 
TListBox 267 
TListBoxData 272 
TProfile class 380 
GetStringLen member function 
TComboBox 104 
TListBox 267 
GetStrings member function 
TComboBoxData 107 
GetSubMenu member function 
TMenu 291 
GetSubText member function 
‘TEdit 196 
GetSymbol member function 
TAutoCommand 575 
TAutolterator 581 
GetSysBoxRect member function 
TTinyCaption 429 
GetSysModalWindow member 
function 
TWindow 471 
GetSystemLangId member 
_ function 
TLocaleString 277 
GetSystemMenu member 
function 
TWindow 471 
GetSystemPaletteEntries 
member function 
TDC 135 


GetSystemPaletteUse member 
function 
TDC 135 
GetTabbedTextExtent member 
function 
TDC 135 
GetTemplate member function 
TDocument 185 
GetText member function 
TComboBox 104 
TStatic 411 
TTextGadget 423 
GetTextAlign member function 
TDC 136 
GetTextCharacterExtra member 
function 
TDC 137 
GetTextColor member function 
TDC 137 
GetTextExtent member function 
TDC 137 
GetTextFace member function 
TDC 137 
GetTextLen member function 
TComboBox 104 
TStatic 411 
GetTextMetrics member function 
TDC 138 
GetThunk member function 
TWindow 471 
GetTitle member function 
TDocument 185 
TPrintout 374, 375 
GetTopIndex member function 
TListBox 268 
GetTopWindow member 
function 
TWindow 472 
GetType member function 
TAutoType 594 
GetUpdateRect member function 
TWindow 472 
GetUpdateRgn member function 
TWindow 472 
GetUserAbort member function 
TPrinter 370 
GetUserLangld member 
function 
TLocaleString 277 
GetValue member function 
TGauge 243 
GetVBXProperty member 
function 
TVbxControl 446 
GetViewld member function 
TView 453 
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-GetViewMenu member function — 


TView 453 


GetViewName member function. 


TDocTemplate 681 
TDocTemplateTD,V 685 
TEditView 206 
TListView 273 
TOleView class 324 
TView 453 
TWindowView 498 
GetViewportExt member 
function 
TDC 138 | 
GetViewportOrg member 
function 
TDC 138 
GetWindow member function 
TEditView 207 
TListView 273 
TOleView class 324 
TView 453 
TWindow 472 
TWindowView 498 
GetWindowClass member 
function 
~TDialog 167 
TWindow 491 
GetWindowExt member 
function 
TDC 138 
GetWindowFont member | 
function 
TWindow 472 
GetWindowLong member 
function 
TWindow 472 
GetWindowOrg member 
function 
TDC 138 
GetWindowPlacement member 
function 
TWindow 473 
GetWindowPtr member function 
TApplication 59 
TWindow 40, 470 
GetWindowRect member 
function 
TOcView 647 
TWindow 473 
GetWindow Task member 
function | 
TWindow 473 
GetWindow Text member 
function | 
TWindow 473 


GetWindowTextLength 
- member function 
TWindow 473 
GetWindowTextTitle member 
function 
TWindow 474 
GetWindowWord member 
function 
TWindow 474 
GetWinMainParams member 
function 
TApplication 59 
GetWordBreakProc member 
function 
TEdit 196 
global enumerations 
TWindowFlag 496 
global functions 40 
accessing 546 
ObjectComponents 523 
pointers, returning 564 
typecasting 555 
globally unique IDs 
acquiring 548 
debugging version, 
servers D449 
GLYPHMETRICS struct 722 
GOBJENUMPROC constant 127 
Graphics Device Interface _ 
classes 245 
graphics objects 14 
grapples, resizing 432 


_ Gray data member 


TColor 99 
GrayString member function 
TDC 138 
GRAYSTRINGPROC 
constant 139 
Green member function 
TColor 100 
group boxes 
creating 250 
notification 252 
radio buttons and 382 
selection, changing 252 
Group data member 
TCheckBox 83 
groupbox.h 21 
GroupCount data member 
TMenuDescr 298 
GUIDGEN nay 548 
GUIDs | 
acquiring 548 
debugging version, 
servers 549 
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H 
H data member 
TDib 174 
TWindowAttr 496 
hAccel data member 
TWindow 490 
HAccTable data member 
TApplication 55 
Handle data member 
TDC 158 
_ TGdiObject 248 
TMenu 292 
TOcInitInfo 620 
HANDLE() operator 
TDib 172 
Handled data member 
TCommandEnabler 112 
HandleGlobalException 305 
HandleMessage member 
function 
TWindow 474 
handler registration key 561 
handles 
brushes 72 . 
dialog boxes 166 
retrieving 194, 197, 471 
Clipboard-viewer 94 
returning 
accelerator tables 307 
client windows 306 
DLLs 309 
parent windows 307 
resources 308 
Windows applications 309 
HANDLETABLE struct 722 
handling exceptions 479 
handling input focus 222 
Has member function 
TBitSet 70 
HasActivePart member function 
TOleWindow 328 
HasFocus member function. 
TDocument 186 
HasHScrollBar data member 
TScroller 395 
HasMember member function 
- TSortedStringArray 409 
HasOption member function 
TValidator 437 : 
HasPage member function 
TPrintout 374 
HasVScrollBar data member 
— TScroller 395 
Hatch11F1[8] data member 
THatch8x8Brush 252 


Hatch13B1[8] data member 
THatch8x8Brush 252 
Hatch13F1[8] data member 
THatch8x8Brush 253 
Hatch22B1[8] data member 
THatch8x8Brush 253 
Hatch22F1[8] data member 
THatch8x8Brush 253 

hatched borders 432 

HBITMAP() operator 
TBitmap 67, 68 

HBottomTB data member 
TOcToolBarInfo 

structure 643 

HBRUSH() operator 
TBrush 72 

HCursor data member’ 
TWindow 490 

HCURSOR() operator 
TCursor 122 

HDC() operator 
TDC 139 

HDROP() operator 
TDropInfo 686 

header files 
ObjectComponents 522 
ObjectWindows 19 

height, rectangles 698 

Height data member 
TLayoutMetrics 259 

Height member function 
TBitmap 67 
TDib 172 
TMetaFilePict 302 
TRect 692 

Help buttons 


events, responding to 565, 


608 


Help files, registering 562, 665 


helpdir registration key 562 
HFILE_ ERROR 211 
HFONT() operator 
TFont 222 
HFrame data member 
TOcToolBarInfo 
structure 643 
HGDIOBJ() operator 
TGdiObject 248 
HIcon data member 
TOcInitInfo 619 
HICON() operator 
TIcon 255 


HideCaret member function 


TWindow 474 
HideList member function 
TComboBox 104 


hierarchy diagrams 7 
Highlightline data member 
TMessageBar 300 
HighValue data member 
TScrollBarData struct 394 
HiliteMenultem member 
function 
TWindow 474 
HInstance data member 
TModule 310 
HINSTANCE() operator 
TModule 309 
hint modes 236 
hint text 300 
HintMode data member 
TGadgetWindow 240 
HintText data member 
TMessageBar 300 
HitTest member function 
THSlider 406 
TSlider 402 
TUlIHandle 435 
TVSlider 407 
HLeftTB data member 
TOcToolBarInfo 
structure 643 
HMenu data member 
TMenultemEnablers 298 
TOcMenuDescr structure 622 
HMENU() operator 
TMenu 291 
HMETAFILE() operator 
TMetaFilePict 302 
HoldFocusHwnd member 
function 
TFrameWindow 224 
TWindow 475 
HoldMenu data member 
TOleFrame 320 
hooks for automation 543 
creating record of 545 
defined 539 
error handling 546 
executing 527 
preventing 544 
reversing commands 548 
verifying arguments 548 
horizontal scroll bars 391 
horizontal sliders 405 
How data member 
TOcInitInfo 619 
HPALETTE() operator 
TPalette 349 
HPEN() operator 
TPen 352 
HPrevInstance data member 
TApplication 55 


HR_ABORT constant 562 
HR_FAIL constant 562 
HR_FALSE constant 563 
HR HANDLE constant 563 
HR_INVALIDARG constant 563 
HR_NOERROR constant 563 
HR_NOINTERFACE 
constant 563 
HR_NOTIMPL constant 563 
HR_OK constant 563 
HR_OUTOFMEMORY 
constant 563 
HR_POINTER constant 563 
HRESULT result codes 562 
HRGN() operator 
TRegion 387 
HRightTB data member 
TOcToolBarInfo 
structure 643 
HScroll member function 
TScroller 397 
HTopTB data member 
TOcToolBarInfo 
structure 643 
_huge keyword 49, 50 
HWindow data member 
TWindow 456 
HWNDQ operator 
TWindow 475 
HWndNext data member 
TClipboardViewer 97 
HWndReceiver data member 
TCommandEnabler 112 
HWhndRestoreFocus data 
member 
TFrameWindow 225 


i_ LPARAM_Dispatch 
function 514 

i_U_W_U_Dispatch 
function 515 

i WPARAM_Dispatch 
function 515 

[32_Dispatch function 515 

132_LPARAM_Dispatch 
function 515 

132_MenuChar_Dispatch 
function 515 

132_U_Dispatch function 515 

I32_WPARAM_LPARAM 
_Dispatch function 515 

_ICLASS macro 535 

icon aspect 608 

icon index registration key 563 
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~ ICONINFO struct 722 
icons 537 
arranging 281 
described 3 
loading into memory 308 
registering 563 
Id data member 
TCommandEnabler 111 
TEventHandler::TEventInfo 
210 
TGadget 232 
TMenuDescr 297 
TResponseTableEntry 388 
TWindowAttr 495 _ 
ID_DEVICE constant 41 
ID_INPUT constant 40 
ID_PAGE constant 41 
ID_PORT constant 41 
ID_PROMPT constant 40 
ID_TITLE constant 41 
IDA_EDITFILE constant 41 
IDA_OLEVIEW constant 41 
IDCANCEL constant 164 
IDD_ABORTDIALOG 
constant 41 | 
IDD_INPUTDIALOG 
constant 40 
IDL APPLICATION 225 
IDI_LASTERISK 225 
IDL EXCLAMATION 225 
IDL HAND 225 
IDL QUESTION 225 
IDispatché&() operator 
TAutoProxy 588 
TAutoVal 596 
IDispatch*() operator 
TAutoProxy 588 
TAutoVal 596 
IdleAction member function 
TApplication 62 
TFrameWindow 224 
TGadgetWindow 238 
TStatusBar 415 
TWindow 475 
TIDM_EDITFILE constant 41 
IDM_OLEPOPUP constant 41 
IDM_OLEVIEW constant 41 
IDOK constant 165 
IDs 
interface objects 469 
retrieving default 166 
IDS_CHILDCREATEFAIL 
constant 43 
IDS_CHILDREGISTERFAIL 
constant 43 


IDS_CLASSREGISTERFAI 
constant 43 | _ 4 


IDS_DOCCHANGED 


constant 42 
IDS_DOCLIST constant 42 
IDS_DOCMANAGERFILE 
constant 42 
IDS_DUPLICATEDOC 
constant 42 | 
IDS_EDITCONVERT 
constant 42 
IDS_EDITOBJECT constant 42 
IDS_EXITSERVER constant 42 
IDS_FILECHANGED 
constant 43 
IDS_FILEFILTER constant 43 
IDS_GDIALLOCFAIL 
constant 44 
IDS_GDICREATEFAIL 
constant 44 
IDS_GDIDELETEFAIL 
constant 44 
IDS_GDIDESTROYFAIL 
constant 44 
IDS_GDIFAILURE constant 44, 
250 | 
IDS_GDIFILEREADFAIL 
constant 44 
IDS_GDIRESLOADFAIL 
constant 44 _ 
IDS_INVALIDCHILDWINDOW 
constant 43 | 
IDS_INVALIDCLIENT- 
WINDOW constant 43 
IDS_INVALIDDIBHANDLE 
constant 44 
IDS_INVALIDMAINWINDOW 
constant 43 
IDS_INVALIDMODULE 
constant 43 
IDS_INVALIDWINDOW 
constant 43 
IDS_LAYOUTBADRELWIN 
constant 43 
IDS_LAYOUTCOMPLETE 
constant 43 
IDS_LISTVIEW constant 44 
IDS_MENUFAILURE 
constant 43 . 
IDS_MODES constant 42 
IDS_MODESOFF constant 42 
IDS_NOAPP constant 43 
IDS_NODOCMANAGER 
constant 42 
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IDS_NOMEMORYFORVIEW 
constant 42 | 

IDS. NOTCHANGED 
constant 42 

IDS_OKTORESUME 
constant 43 

IDS_OUTOFMEMORY 
constant 43 | 

IDS_OWLEXCEPTION 
constant 43 


IDS_PRINTERERROR 


constant 43 | 
IDS_PRNCANCEL constant 44 
IDS_PRNERRORCAPTION 

constant 44 
IDS_PRNERRORTEMPLATE 

constant 44 
IDS_PRNGENERROR 

constant 44 | 
IDS_PRNMGRABORT 

constant 44 
IDS_PRNON constant 44 
IDS_PRNOUTOFDISK 

constant 44 
IDS_PRNOUTOFMEMORY 

constant 44 
IDS_READERROR constant 42 
IDS_UNABLECLOSE 

constant 42 
IDS_UNABLEOPEN 

constant 42 


IDS_UNABLEREAD 


constant 43 
IDS_UNABLEWRITE 
constant 43. 
IDS UNHANDLEDXMSG 
constant 43 
IDS_UNKNOWNERROR 


- constant 43 


IDS_UNKNOWNEXCEPTION 
constant 43 

IDS_UNTITLED constant 42 

IDS_UNTITLEDFILE 
constant 43 

IDS_VALIDATORSYNTAX 
constant 43 

IDS_VALINVALIDCHAR 
constant 44 

IDS_VALNOTINLIS constant 45 

IDS_VALNOTINRANGE 
constant 45 

IDS_VALPXPCONFORM 
constant 44 

IDS_VIEWLIST constant 42 


IDS_WINDOWCREATEFAIL 
constant 43 
IDS_WINDOWEXECUTEFAIL 
constant 43 
IDW_FIRSTMDICHILD 
constant 281 
IDW_MDICLIENT constant 45, 
281 : 
IDW_MDIFIRSTCHILD 
constant 45 
_IFUNC macro 535 
ILockBytes interface 418 
_import keyword 49, 50 
Index member function 
TColor 101 
indexes, list position 265, 266, 
267, 268, 269 
indicators, status bar 413, 415 
borders 415 
spacing 414, 415, 416 
Inflate member function 
TRect 692 
InflatedBy member function 
TRect 692 
Info data member 
TDib 174 
InfoFromHandle member 
function 
TDib 175 
inheritance diagrams 25 
INI files 379 
Init member function 
TAutolterator 582 
TDC 159 
TFindReplaceDialog 218 
TFrameWindow 227 
TOleWindow 339 
TOpenSaveDialog 344 
TWindow 493 
InitApplication member function 
TApplication 62 
InitChild member function 
TMDi!IClient 282 
InitDoc member function 
TDocManager 180 
TDocTemplate 681 
TDocument 186 
TOleDocument 313 
InitialDir data member 
TOpenSaveDialog::TData 346 
initialization 
animated objects 582 
dialog boxes 164, 166 
instance 55 
initialization files 379 


InitInfo data member 
TOcDragDrop structure 613 


integers, testing for range 383 
interface elements 


InitInstance member function 
TApplication 62 

InitMainWindow member 

function 

TApplication 62 

InitModule member function 
TModule 307 

InitView member function 
TDocTemplate 681 

in-place editing 
merging menus 621 
showing tool bars 642 

input dialog windows 255 

input fields 215 
defining character sets 215 
invalid entries 215, 278, 421, 

438, 439 

input focus 222 

inputdia.h 21 

Insert member function 
TDecoratedFrame 160 
TDocument::List 190 
TEdit 196 
TGadgetWindow 238 
TStatusBar 414 
TToolBox 431 

insertable registration key 563 

Inserted member function 
TControlGadget 117 
TGadget 233 

inserting an object 618 

inserting OLE objects 601 

InsertMenu member function 
TMenu 291 

InsertString member function 
TComboBox 105 
TListBox 268 

instance initialization 55 

InstanceCount data member 
TXBase 700 

InStream member function 
TDocument 186 
TFileDocument 212 
TStorageDocument 418 

int far*() operator 
TAutoVal 596, 597 

int member function 
TOcPartCollectionlter 634 

int typedef 408 

int() operator 
TAutoString 593 
TAutoVal 597 
TOcFormatListIter 616 
TOcPartCollectionIter 634 
TStatus 412 


autocreation 
disabling 463 
enabling 464 
controls 117 
destroying 463 
dialog boxes 165 
interface objects 
child windows 459 
closing, conditional 458 
data, transferring 463, 488 
flags, setting 483 
group boxes 250 
IDs 469 
list boxes 264 
registration class name 491 
scrolling 491 
setting up 161, 227, 493 
showing 487 
static text 410 
status 412, 456 
transfer mechanism 
disabling 463 
enabling 464 
window objects 491 
international 
language, setting 599 
registration strings, 
localizing 564 
IntersectClipRect member 
function 
TDC 139 
invalid characters 
checking for 215, 422, 437 
numeric values 383 
picture formats 381 
Invalidate member function 
TButtonGadget 78 
TControlGadget 117 
TGadget 233 
TOcRemView 638 
TTextGadget 424 
TWindow 475 
InvalidatePart member function 
TOcView 648 
TOleWindow 339 
InvalidateRect member function 
TControlGadget 117 
TGadget 233 
TWindow 475 
InvalidateRen member function 
TWindow 475 
invalidating buttons 78 
InvertRect member function 
TDC 139 
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InvertRgn member function 

TDC 140 
Invoke member function — 

: TAutoCommand 575 
TAutoProxy 589 

IsActive member function 
TOcPart 628 

IsArrayProp member function 
TVbxControl 444 


IsAutoMode member function 


TScroller 397 

IsBound member function 

TAutoProxy 588 

IsChild member function 
TWindow 476 

IsClipboardFormatAvailable 

member function 

TClipboard 95 

IsCore data member 
TDib 175 | 

IsCurrentDefPB data member 
TButton 73 

IsDefPB data member 

_ TButton 73 

IsDirty member function 

TDocument 186 

IsDlgButtonChecked member 

function 

TWindow 476 

IsEmbedded member function 
TDocument 186 

IsEmpty member function 
TBitSet 70 
TOcFormatList 615 
TOcNameList 625 
TOcPartCollection 632 
TRect 693 
TSortedStringArray 409 

IsFlagSet member function 
TDocManager 180 
TDocTemplate 681 
TWindow 476 

IsFull member function 
TSortedStringArray 410 

IsHorizontal data member 
TGauge 244 

IsIconic member function 
TWindow 476 

IsLoaded member function 
TModule 307 

IsModal data member 
TDialog 164 

IsModified member function. 
TEdit 196 


IsMyKindOfDoc member 
function 
TDocTemplate 682 
TDocTemplateTD,V 684 
IsMyKindOfView member 
function 
TDocTemplateTD,V 685 


-IsMyKindofView member 


function 

TDocTemplate 682 

IsNativelangId member function 
TLocaleString 277 

IsNull member function | 
TRect 693 

IsOK member function 
TDib 172 
TMenu 291 
TView 453 

IsOpen data member 
TClipboard 96 

IsOpen member function 

 TDocument 186 

TFileDocument 212 
TStorageDocument 418 

IsOpenEditing member function 
TOcRemView 639 

IsOptionSet member function 
TOcApp 604 | 
TOcModule 623 
TRegistrar 655 

IsPM member function 
TDib 172 

IsPressed data member 
TTinyCaption 426 

IsPropSet member function 
TAutoCommand 575 

IsReceiver member function 
TCommandEnabler 112 

IsRef member function 
TAutoVal 597 

IsResHandle data member 
TDib 175 

IsSelected member function 
TOcPart 629. 

IsStatic member function 
TDocTemplate 682 

IsString member function 
TResId 697 

IsValid member function 
TEdit 196 
TFilterValidator 215 
TLookupValidator 278 
TPXPictureValidator 381 
TRangeValidator 383 
TValidator 438 

IsValidInput member function 
TFilterValidator 215 
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TPXPictureValidator 381 
TValidator 438 
IsVisible member function 
TDocTemplate 682 
TOcPart 629 a 
IsVisibleRect member function 
TScroller 397 
IsWindow member function 
TWindow 476 
IsWindowEnabled member 
function 
TWindow 476 
IsWindow Visible membe 
function : | 
TWindow 476 
IsZoomed member function 
TOcScaleFactor 642 
TWindow 476 
ItemDatas data member 
TComboBoxData 108 
TListBoxData 270 
Iterate member function 
TAppDictionary class 55 
iteration 
automation servers 543, 557 
objects 581 
iterator member functions 
child windows 466 
TUnknown&() operator 
TAutoVal 597 
TUnknown 659 
TUnknown() operator - 
TAutolterator 582 | 
TUnknown‘*() operator 
TAutoVal 597 
TUnknown. 659 


K 


KERNINGPAIR struct 723 
Key data member 
TXRegistry 665 
keyboard navigation 
TMDI frame 285 
KeyboardHandling data 
~ member 
TFrameWindow 223 
KillTimer member function 
TWindow 476 


L 
LanglId data member 
TAutoStack 592 


language registration key 564 


LastThat member function 
TSortedStringArray 410 


layout constraints, creating 
windows 256, 258 
Layout member function 
TLayoutWindow 264 
layout metrics 46 
layout units 258 
layoutco.h 21 
LayoutSession member function 
TGadgetWindow 238 
TToolBox 431 
LayoutUnitsToPixels member 
function 
TGadgetWindow 242 
layoutwi.h 21 
LBN_DBLCLK constant 45 
LBN_ERRSPACE constant 45 
LBN_KILLFOCUS constant 45 
LBN_SELCANCEL constant 46 
LBN_SELCHANGE constant 46 
LBN_SETFOCUS constant 46 
LBS_NOTIFY constant 265 
LBS_SORT constant 265 
LButtonDown member function 
TButtonGadget 78 
TGadget 233 
LButtonUp member function 
TButtonGadget 78 
TGadget 233 
LedSpacing data member 
TGauge 244 
LedThick data member 
TGauge 244 
LeftOf member function 
TEdgeConstraint 191 
libraries _ 
dynamic link 17 
ObjectComponents 521 
OLE applications 561 
registering Help files 562, 665 
summary 16 
version number, returning 50 
version, registering 666 
linefeeds 194 
LineMagnitude data member 
TScrollBar 391 
LineTo member function 
TDC 140 
Link data member 
TOcView 650 
linking ObjectComponents 
classes 530 
linking ObjectComponents 
enums 532 
linking ObjectComponents 
messages 532 - 


linking ObjectComponents 
structs 532 
links, modifying 646 
list boxes 119, 270 
clearing 265 
creating 264 
entries 
adding 265 
deleting 265 
getting 267 
initializing 271 
inserting 268 
length of 267 
number of 266, 267 
selecting 267, 269 
transferring 270 
message constants 45 
registration class name 270 
strings, adding to 270 
strings, transferring 270 
transfer structures 270 
List nested class 
TDocument 189-190 
list view ID constants 44 
listbox.h 21 
lists, documents 189 
listview.h 22 
LmFParent constant 46 
Load member function 
TOcPart 629 
TOcRemView 639 
LoadAccelerators member 
function 
TModule 307 
LoadAcceleratorTable member 
function 
TWindow 493 
LoadBitmap member function 
TModule 307 
LoadBOle member function 
TOcRegistrar 637 
LoadCursor member function 
TModule 308 
LoadData member function 
TEditView 207 
TListView 275 
LoadFile member function 
TDib 175 
LoadIcon member function 
TModule 308 
loading objects 566, 629, 639 
compound documents 611 
LoadMenu member function 
TModule 308 
LoadParts member function 
TOcDocument 611 


LoadResource member function 
TDib 175 
TModule 308 
LoadString member function 
TModule 308 
locale.h 22 
locales 
IDs 599 
overriding 564 
registration strings 564 
localizing string resources 276 
Locate member function 
TOcPartCollection 633 
Lock member function 
TPrintDialog::TData 367 
LockBuffer member function 
TEdit 196 
LockWindowUpdate member 
function 
TWindow 477 
LOGBRUSH struct 723 
LogFont data member 
TChooseFontDialog::TData 
91 
LOGFONT struct 725 
logical points 310 
LOGPALETTE struct 727 
LOGPEN struct 728 
long far*() operator 
TAutoVal 597 
long types 583 
long() operator 
TAutoVal 597 
Lookup member function 
TAutoProxy 588 
TLookupValidator 279 
TStringLookupValidator 422 
lookup validators 278 
string 421 
LookupError member function 
TAutoCommand. 575 
LowerBound member function 
TSortedStringArray 410 
LowMemory member function 
TModule 308 
LowValue data member 
TScrollBarData struct 395 
LParam parameter 
control messages 167 
lpCmdLine data member 
TModule 304 | 
LPtoDP member function 
TDC 140 
LPtoSDP member function 
TPrintPreviewDC 376 
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LtBlue data member 
TColor 99 

LtCyan data member 
TColor 99 — 

LtGray data member 
TColor 99 

LtGreen data member 
TColor 99 

LtMagenta data member 
TColor 100 | 

_ LtRed data member 

| TColor 100 

LtYellow data member 
TColor 100 


MACROGEN utility 538 


macros 
automation controllers 528, 
538, 544 
automation servers 525, 526, 
547, 556, 571 
accessing data 
members 539 
accessing member 
functions 542, 546 
accessing properties 545, 
559, 560 
bit flags 541 — 
combining unrelated 
classes 556, 557 
defining automatable 
members 551, 552, 555, 
573 
destroying objects 540 
enumerated types 541 
exposing members 558 
hooks 543, 545, 548 
defined 539 
error handling 546 
executing 527 
preventing 544 
iteration 543, 557 
class modifier 539 
— creating COM objects 551 
declaration specifiers 535 
event handling 31, 36 
GDI objects 248-249 
response tables 32, 35 
Magnitude member function 
TSize 698 | 
main window 284 
closing 57, 459, 460 
creating 55, 62 
naming 62 
nCmdShow display 56 
status 304 


MainWindow variable 62 


~MakeWindow member function 


TModule 308 

Map enum 169 

MapColor member function 
TDib 172 

MapIndex member function 
TDib 172 

MappingMode member function 
TMetaFilePict 302 

MapStatusCodeToString 

member function 

TXCompatibility 500 

MapUIColors member function 
TDib 173 


‘MapWindowPoints member 


function 
TWindow 477 
Margin constant 258 
Margin data member 
TGauge 244 
margins for gadgets 239 
Margins data member 
TGadget 232 
TGadgetWindow 240 
MaskBlt member function 
TDC 140 © 
MatchTemplate member 
function | 
TDocManager 180 
mathematical classes 
overview 15, 671 
matrix 3 | 
toolbox arrangement 430 
Max data member 
TGauge 244 
TRangeValidator 384 
TSlider 404 
MAX_RSRC_ERROR_STRING 
constant 46 
maximum values 
checking for 384 
MaxPage data member 
TPrintDialog::TData 366 
MaxWidth data member 
TListView 273 
MB_ABORTRETRYIGNORE 
constant 46 
MB_APPLMODAL constant 47, 
57 
MB DEFBUTTONI constant 47 
MB_DEFBUTTON2 constant 47 


MB_DEFBUTTONS constant 47 » 


MB_ICONASTERISK 
constant 47 
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MB_ICONEXCLAMATION 
constant 46 
MB_ICONHAND constant 46, 
47 
MB_ICONINFORMATION 
constant 47 | 
MB_ICONQUESTION 
constant 46 
MB_ICONSTOP constant 47 
MB_OK constant 46 
/MB_OKCANCEL constant 46 
MB_RETRYCANCEL 
constant 46 
MB_SYSTEMMODAL 
constant 47, 57 
MB_TASKMODAL constant 47, 
57 
MB_YESNO constant 46 
MB_YESNOCANCEL 
constant 46 
MDI child ID constant 45 
MDI client constant 45 
MDI functions, invoking 31 
mdi.h 22 
mdichild.h 22 
MDICREATESTRUCT 
struct 728 
MDIFILE.CPP 502 
Measureltem member function 
TControl 119 
TMenu 291 
MEASUREITEMSTRUCT 
struct 729 
measurement units, 
windows 286 
mediums of transfer, 
registering 568 
Mem data member 
TOleAllocator 653 
member function types 
TActionFunc 51, 466 
TActionMemFunc 51, 466 
TAnyAnyDispatcher 52 
TAnyPMEF 51 
TCondFunc 114, 466 
TCondMemFunc 114, 466 
member functions 
defining 114 
event handling 36 
obsolete 166, 167 
pointers, generic 51 
memory | 
freeing 201 
- managing 303 
memory allocator, 


specifying 652 


Menu data member 
TWindowAttr 495 
menu descriptors 
deleting 223 
menu objects 288 
menu resource ID 495 
menu.h 22 | 
Menultemld data member 
TDecoratedFrame 161 
menuname registration key 564 
menus 13 
automated objects and 570, 
665, 666 
creating 353, 422 
ID constants 41 
loading into memory 308 
merging 621 
system 422 
Merge member function 
TMenuDescr 297 
MergeMenu member function 
TFrameWindow 224 
MergeModule data member 
TFrameWindow 226 
merging menus 621 
message bars 
hint text 300 
implementation 299 
message boxes 
errors 305 
message constants 
backward compatible 43 
dialog boxes 46 
document 34 
GDI 44 
list box 45 
TXWindow class 43 
message dispatcher 52 
message queties 606 
messageb.h 22 
MessageBox member function 
~ TWindow 477 
MessageLoop member function 
_TApplication 59 
MessageLoopResult data 
member 
TApplication 61 
messages 413 
See also message bars 
error See error messages 
exception constants 43 
preprocessing 160, 167 
processing 165, 456, 460, 565 
incoming 463 
response 226 7 
sending to dialog boxes 167 
WM_OCEVENT 667 


metafile.h 22 
metafiles 300, 301 
METARECORD struct 729 
Method member function 
TVbxControl 444 
MF_BITMAP constant 290 
MF BYCOMMAND 
constant 289, 290 
MF_BYPOSITION constant 289, 
290 
MF CHECKED constant 289, 
290 | 
MF_DISABLED constant 290 
MF ENABLED constant 290 
MF_GRAYED constant 290 
MF MENUBARBREAK 
constant 290 
MF MENUBREAK constant 290 
MF SEPARATOR constant 290 
MF UNCHECKED 
constant 289, 290 
MFENUMPROC parameter 127 
Min data member 
TGauge 244 
TRangeValidator 384 
TSlider 404 
minimum values 
checking for 384 
MinPage data member 
TPrintDialog::TData 366 
Mm data member 
TMetaFilePict 303 
modal dialog boxes 163, 164 
mode constants 42 
Mode data member 
TDib 175 
mode flags, setting 188 
mode indicators 413, 415 
borders 415 
spacing 414, 415, 416 
Modelndicators data member 
TStatusBar 415 
ModelndicatorState data 
member 
TStatusBar 415 
modeless dialog boxes 
creating 388 
ModifyMenu member function 
TMenu 291 
ModifyWorldTransform 
member function 
TDC 141 
module classes 13 
Module data member 
~ TMenuDescr 298 
TModule 304 


module.h 22 
modules 55 
DLL stand-in 303 
instance handles 309 
MostDerived function 564 
mouse objects 
button state 28 
MouseEnter member function 
TButtonGadget 78 
TGadget 233 
MouseLeave member function 
TButtonGadget 78 
TGadget 234 
MouseMove member function 
TButtonGadget 79 
TGadget 234 
MouseOffset data member 
TSlider 404 
Move member function 
TUIHandle 435 
TVbxControl 444 
MoveTo member function 
TDC 142 
TUlIHandle 436 
MoveWindow member function 
TWindow 477 
Msg data member 
TEventHandler::TEventInfo 
210 
TResponseTableEntry 389 
Msg member function 
TGdiObject::TXGdi 250 
TXWindow 500 
MSG struct 730 
multiple document interface 
child windows 279 
cascading 283 
closing 283 
creating 282, 283 
tiling 283 
client windows 281 
freeing 281 
icons, arranging 283 
main window 284 
multiuse servers 570, 665 
MustBeBound member function 
TAutoProxy 589 
MyEdge data member 
TLayoutConstraint 257 


Name data member 
TDialog::TDialogAttr 168 

named streams 212 

names, servers, registering 564 

NBits function 47 
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_NCels data member 
TCelArray 82 
nCmdShow data member 
TApplication 56 
NColors function 47 
nested classes 


TXInvalidModule class 310 


TXInvalidWindow class 63 
‘TXMenu class 501 
TXPrinter class 372 
TXValidator class 440 
TXWindow class 499 

NewFile member function 
TEditFile 203 | 

NewsStringList member function 
TStringLookupValidator 422 

Next member function 
TDocument::List 190 
TWindow 478 

NextBand member function 

~-TPrintDC 362 

NextGadget member function 
TGadget 231 
TGadgetWindow 238 

NextStream data member 
TStream 421 | 

NextStream member function 
TDocument 186 

NextView member function 
TDocument 186 

non-client events 424 

Normalize member function 
TRect 693 

Normalized member function 
TRect 693 

NotchCorners data member 
TButtonGadget 76 

notification codes 200 

NotifyCode data member 
TResponseTableEntry 389 

NotifyParent data member 
TGroupBox 251 

NotifyParent member function 
THSlider 406 
TSlider 403 
TVSlider 407 | 

Notify Views member function 
TDocument 186 

NotOK member function 
TView 454 

NumCels member function 
TCelArray 81 

NumChars data member 
TTextGadget 423 

NumChildren member function 
TWindow 478 


NumClrs data member 
~TDib 175 © 


~ numColors member function 


TDib 173 | : 
NumColumns data member 
TToolBox 431 | 

numeric values 
checking 383, 438 
“ranges, testing for 383 
setting maximum/ 
minimum 384 
NumGadgets data member 
TGadgetWindow 240 
NumModelndicators data 
member 
TStatusBar 415 
NumRows data member 
TToolBox 431 
numScans member function 
TDib 173 


0 


OBJ_REF_ADD macro 248 


OBJ_REF_ COUNT macro 249 
OBJ REF DEC macro 249 
OBJ_REF_INC macro 249 

OBJ REF REMOVE macro 249 


_ Object data member 


TEventHandler::TEventInfo 
210 
Object member function 
TAutoEnumerator 580 
Object Support Library 16 


ObjectComponents | 
applications, debugging 550 


automation classes 523, 524 
registering 572 
class modifier 539 
event messages 565 
exception classes 523 
global functions 523 
header files 522 
libraries 521 
linking and embedding 530, 
532 
registration strings, 
localizing 564 
ObjectPtr typedef 564 
objects 
collections 543, 557 
enumerating 579,581 | 
connector 600 
copying 585, 602 
delegating 556, 557 


dragging 602 
drawing 566 
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embedded See embedded 
objects 
exposing 547 
formats, converting 602. 
initializing 582 
iteration 581 
painting 566 
pasting 604 
pointers 564 
_ polymorphic 564 
printing 537, 567 
registering 665, 666 
viewing 536 
windows 491 
OC_APPBORDERSPACEREQ 
event message 565 
OC_APPBORDERSPACESET 
event message 565 
OC_APPDIALOGHELP event 
message 565 | 
OC_APPFRAMERECT event 
message 565 | 
OC_APPINSMENUS event 
message 565 
OC_APPMENUS event . 
message 565 
OC_APPPROCESSMSG event 
message 565 
OC_APPRESTOREUI event 
message 565 
OC_APPSHUTDOWN event 
message 565 
OC_APPSTATUSTEXT event 
message 565 
OC_VIEWATTACHWINDOW 
event message 566 
OC_VIEWBORDERSPACEREQ 
event message 566 
OC_VIEWBORDERSPACESET 
event message 566 
OC_VIEWCLIPDATA event 
message 566 
OC_VIEWCLOSE event 
message 566 
OC_VIEWDRAG event 
message 566 
OC_VIEWDROPFP event 
message 566 
OC_VIEWGETPALETTE event 
message 566 
OC_VIEWGETSCALE event 
message 566 | 
OC_VIEWGETSITERECT event 
message 566 
OC_VIEWINSMENUS event 
message 566 


OC_VIEWLOADPART event 
message 566 
OC_VIEWOPENDOC event 
message 566 
OC_VIEWPAINT event 
message 566 
OC_VIEWPARTINVALID 
event message 566 
OC_VIEWPARTSIZE event 
message 566 
OC_VIEWSAVEPART event 
message 566 
OC_VIEWSCROLL event 
message 566 
OC_VIEWSETSCALE event 
message 566 
OC_VIEWSETSITERECT event 
message 566 
OC_VIEWSHOWTOOLS event 
message 566 
OC_VIEWTITTLE event 
message 566 
OcApp data member 
TOcModule 624 
TOcView 650 
TOleWindow 329 
OcDoc data member 
TOleWindow 330 
OcDocument data member 
TOcView 650 
_OCFCLASS macro 536 
_OCFDATA macro 536 
_~OCFFUNC macro 536 
OcInit data member 
~  TOcModule 623 
ocrActivateWhen Visible 
constant 569 
ocrBitmap constant 567 
ocrCanLinkByOle1 constant 569 
ocrCantLinkInside constant 569 
ocrChecked constant 571 
ocrContent constant 567 
ocrDib constant 567 
ocrDif constant 567 
ocrDisabled constant 571 
ocrDocPrint constant 567 
ocreg.h 533 
ocrEmbeddedObject 
constant 567 
ocrEmbedSource constant 567 
ocrEnhMetafile constant 567 
ocrFile constant 569 
ocrFormatLimit constant 568 
ocrGDI constant 569 | 
ocrGet constant 568 
ocrGetSet constant 568 


ocrGrayed constant 571 
ocrHGlobal constant 569 
ocricon constant 567 
ocrInsertNotReplace 
constant 569 
ocrInsideOut constant 569 
ocrIsLinkObject constant 569 
ocrIStorage constant 569 
ocrIStream constant 569 
ocrLinkSource constant 567 
ocrLinkSrcDescriptor 
constant 568 
ocrMenuBarBreak constant 571 
ocrMenuBreak constant 571 
ocrMetafilePict constant 567 
ocrMfPict constant 569 
ocrMultipleLocal constant 570 
ocrMultipleUse constant 570 
ocrNeverDirties constant 570 
ocrNoSpecialRendering 
constant 569 
ocrObjectDescriptor 
constant 568 
ocrOemText constant 567 
ocrOnContainerMenu 
constant 570 
ocrOnlylIconic constant 569 
ocrPalette constant 567 
ocrPenData constant 567 
ocrRecomposeOnResize 
constant 569 
ocrRenderingIsDevice- 
Independent constant 569 
ocrRichText constant 567 
ocrRiff constant 567 
ocrSet constant 568 
ocrSingleUse constant 570 
ocrStatic constant 569 
ocrSylk constant 567 
ocrText constant 567 
ocrThumbnail constant 567 
ocrTiff constant 567 
ocrUnicodeText constant 567 
ocrVerbLimit constant 568 
ocrWave constant 567 
ocrxxxx constants 533 
OcView data member 
TOleWindow 330 
ODADrawEntire member 
function 
TControl 119 
ODAFocus member function 
TControl 119 
ODASelect member function 
TControl 119 


ofAppend constant 48 
ofAtEnd constant 48 
ofBinary constant 48 
Offs data member 
TCelArray 82 
Offset member function 
TCelArray 81 
TPoint 687 
TRect 693 
OffsetBy member function 
TPoint 687 
TRect 693 
OffsetClipRgn member function 
TDC 142 
OffsetViewportOrg member 
function 
TDC 142 
TPrintPreviewDC 376, 378 
OffsetWindowOrg member 
function 
TDC 142 
oflosMask constant 48 
ofn data member 
TOpenSaveDialog 343 
OFN_ALLOWMULTISELECT 
constant 346 
OFN_CREATEPROMPT 
constant 346 
OFN_EXTENSIONDIFFERENT 
constant 346 
OFN_FILEMUSTEXIST 
constant 345 


OFN_HIDEREADONLY 


constant 345 
OFN_NOCHANGEDIR 
constant 346 
OFN_NOREADONLYRETURN 
constant 346 
OFN_NOTESTFILECREATE 
constant 346 
OFN_NOVALIDATE 
constant 345 
OFN_OVERWRITEPROMPT 
constant 346 
OFN_PATHMUSTEXIST 
constant 345 
OFN_SHAREAWARE 
constant 346 
OFN_SHAREFALLTHROUGH 
constant 346 
OFN_SHAREWARN 
constant 346 
OFN_SHOWHELP constant 346 
ofNoCreate constant 48 
ofNoReplace constant 48 
ofParent constant 48 
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ofPreserve constant 48 
ofPriority constant 48 — 
ofRead constant 48 
ofReadWrite constant 48 
offemporary constant 48 
ofTransacted constant 48 
ofTruncate constant 48 
ofWrite constant 48 
OLE applications 522 
accessing automated 
classes 525, 526 
automation commands 528 
Clipboard formats 561 
drawing objects 561 
events 565 
exposing 556 
interface, implementing 535, 
600 
menu IDs 41 
messages, processing 565 
registering arguments 549 
running 604, 606, 607 
string resources 276 
version, registering 666 
OLE clients 310 
OLE functions 
modifying 535 
return codes 562 
OLE programs 
compatible constants 48 
oledoc.h 22 
olefacto.h 22 
oleframe.h 22 
OleMalloc data member 
TOcModule 624 
olemdifr.h 22 
oleview.h 22 
olewindo.h 22 
Open member function 
TDocument 187 
TEditFile 203 
TFileDocument 212 
TOcPart 629 
TOleDocument 313 
TStorageDocument 418 
OpenClipboard member 
function 
TWindow 478 
OpenHandle member function 
TStorageDocument 418 
opening documents 
path 188 
opening files 
file error 213 
opensave.h 22 
OpenThisFile member function 
TFileDocument 213. 


operators, dereference 584, 585. 
operators (predefined classes) 
TAutolterator 582 
TAutoObject 584, 585 
TAutoObjectByVal 585 
TAutoObjectDelete 586 
TAutoProxy 588 | 
TAutoString 593 
TAutoVal 595, 597 
TBitmap 67, 68 
TBitSet 70,71 
TBrush 72 
TCelArray 81 
TCharSet 83 
TClipboard 95 
TColor 100 
TCursor 122 
TDC 139 
TDib 170, 172, 173, 174 
TFont 222 
TGdiObject 248 | 
TIcon. 255 
TLocaleString 277 
TMenu 291, 292 
TMetaFilePict 302 
TModule 309 
TOcFormatListlter 616 
TOcNameList 625 
TOcPart 626 | 
TOcPartCollectionlter 634 
TOcScaleFactor 641 
TPalette 349 
TPen 352 
TProcInstance 690 
TRect 694 
TRegion 386, 387 
TSortedStringArray 410 
TStatus 412 
TStatusBar 414 
TWindow 475 
OPTIONAL_ARG macro 571 
Options data member | 
TValidator 439 
OrgBitmap data member 
TMemoryDC 288 
OrgBrush data member 
TDC 158 
OrgFont data member 
TDC 158 
OrgPalette data member 
TDC 158 © 
OrgPen data member 
TDC 159 
OrgTextBrush data member 
TDC 159 
origin 310 
brush object 72 
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Origin data member 
TEditView 207 
TListView 274 
TOcView 651 

OtherEdge data member 
TLayoutConstraint 257 

Outer data member 
TUnknown 660 


~ OUTLINETEXTMETRIC 


struct 731 | 
OutStream member function 
TDocument 187 
TFileDocument 212 
TStorageDocument 419 
owlall.h 22 
_OWLCLASS macro 18, 49 
OWLCMD.CPP 424 
owlcore.h 22 
_OWLDATA macro 18, 49 
owldefs.h 22 
—OWLDLL macro 49° 
~OWLFAR macro 50 
_OWLFARVTABLE macro 19, 
50 
_OWLFASTTHIS macro 50 
OWLFastWindowFrame 
member function — 
TDC 143 
~OWLFUNC macro 50 
OWLGetVersion member 
function 50 
owlpch.h 22 
Owner data member 
TAutolterator 583 
TAutoStack 592 


p 


P data member 
TAutoObject 585 
PageMagnitude data member 
TScrollBar 391 - 
PageSize data member 
TPrinter 371 
TPrintout 375 
pagination 374 
page ranges 374 
Paint data member 
TOcViewPaint structure 652 
Paint member function 
TBitmapGadget 69 
TButtonGadget 79 
TGadget 234 
TGadgetWindow 242 
TGauge 245 
TOleWindow 339 | 
TPreviewPage 355 


TTextGadget 424 
TUlIHandle 436 
TWindow 478 
PAINT.CPP 220 
PaintBorder member function 
TGadget 234 
TGauge 245 
PaintButton member function 
TTinyCaption 429 
PaintCaption member function 
TTinyCaption 429 
PaintCloseBox member function 
TTinyCaption 430 
PaintGadgets member function 
TGadgetWindow 242 
TMessageBar 300 
painting 
controls 79 
horizontal rulers 406 
objects 627, 638, 648, 651 
event messages 566 
slots 406 
windows 226 
PaintMaxBox member function 
TTinyCaption 430 
PaintMetafile member function 
TOleWindow 328 
PaintMinBox member function 
TTinyCaption 430 
PaintParts member function 
TOleWindow 339 
PaintRgn member function 
TDC 143 
PaintRuler member function 
THSlider 406 
TSlider 403 
TVSlider 407 
PaintSlot member function | 
THSlider 406 
TSlider 403 
TVSlider 407 
PAINTSTRUCT struct 738 
PaintSysBox member function 
TTinyCaption 430 
PaintThumb member function 
TSlider 403 
PaintToPos member function 
THSlider 406 
PALETTEENTRY struct 738 
Pallndex member function 
TColor 101 
PalRelative member function 
TColor 101 
Param data member 
TDialog::TDialogAttr 168 
TWindowAttr 495 


parameters 
automated methods 574 
Parent data member 
TWindow 456 
parent windows 456 
handles, returning 307 
PartSize member function 
TOcScaleFactor 641 
passwords 195, 197 
Paste member function 
TEdit 196 
TOcApp 604 
TOcView 648 
pasting objects 604, 618, 646, 648 
PatBlt member function 
TDC 143 
Path data member 
TOcInitInfo 619 
path registration key 571 
PathChanged member function 
TOleDocument 313 
paths, document 188 
PathToRegion member function 
TDC 143 
patterns, border 432 
pd data member 
TPrintDialog 368 
pens 351 
Percent constant 258 
PercentOf member function 
TEdgeConstraint 191 
TEdgeOrSizeConstraint 192 
PerformCreate member function 
TEditView 207 
TMDIChild 280 
TMDIFrame 286 
TVbxControl 446 
TWindow 478 
PerformDligInit member function 
TDialog 167 
permid registration key 572 
pfConstant constant 48 
pfGetBinary constant 48 
pfGetText constant 48 
pfHidden constant 49 
pfSettable constant 48 
pfUnknown constant 48 
pfUserDef constant 49 
Pic data member 
TPXPictureValidator 382 
Picture member function 
TPXPictureValidator 381 
picture strings 
checking 380 
valid characters 381 
picture validators 380 


Pie member function 
TDC 143 

placing gadgets 353 

Planes member function 
TBitmap 67 

PlayMetaFile member function 
TDC 144 

PlayMetaFileRecord member 

function 

TDC 144 

PlayOnto member function 
TMetaFilePict 302 

PlgBlt member function 
TDC 144 

Pmf data member 
TResponseTableEntry 389 

-po compiler option 50 

pointers 
far data 50 
member functions 51, 389 

message dispatchers 513 

returning 564 
transfer buffers 106 
typecasting 555, 584 | 
void 564 

PointSize data member 
TChooseFontDialog::TData 

91 

PointToPos member function 
TSlider 403 
TVSlider 407 

PolyBezier member function 
TDC 145 

PolyBezierTo member function 
TDC 145 

PolyDraw member function 
TDC 145 

Polygon member function 
TDC 146 

Polyline member function 
TDC 146 

PolylineTo member function 
TDC 146 

polymorphic objects 564 

PolyPolygon member function 
TDC 146 

PolyPolyline member function 
TDC 147 

pop-up menus 353 

Pos data member 
TOcDragDrop 613 
TOcViewPaint 652 
TOleWindow 330. 
TSlider 404 

position 
carets, returning 195, 197 
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aimee edit control . 192, 
195 
~. combo boxes 
relative to origin 102 
current 197, 487 
coordinates 391 
list box 265, 266 
moving 393 
text selection 195, 267, 268, 
269 
edit controls 
tab stops in 197 
relative to origin 118, 193, 
251, 265, 382 
scroll bar, thumb 391 
range 392 
setting 392, 393 
tracking 393 
specified by variables 194, 
197 
Position data member 
TMenultemEnablers 298 
TScrollBarData struct 395 
PositionGadget member function 
TControlBar 116 
TGadgetWindow 242 
TStatusBar 416 
PostDispatchAction member 
function . 
TApplication 59 
PostDocError member function 
TDocManager 181 
PostError member function 
~  ‘TDocument 187 
PostEvent member function — 
TDocManager 181 
PostMessage member function 
TWindow 478 
PosToPoint member function 
THSlider 406 
TSlider 403 
TVSlider 408 
-prComplete constant 381 
. PreOpen member function 
TOleDocument 313 
PreProcessMenu member 
function | 
TApplication 60 
PreProcessMsg member function 
TControlBar 116 
TDecoratedFrame 160 
TDialog 167 
TFrameWindow 224 
TMDIChild 280 
TMD!IClient 282 
TStatusBar 416 
TWindow 478 


prError constant 381 

Pressed data member 
TButtonGadget 77 

preview.h 22 


previewing data 375 


previewing pages 354 
Previous member function 
TWindow 479 
princomplete constant 353, 381 
Print member function — 
_ TPrinter 370 
print preview classes 354, 375 
print setup dialog boxes 
controls, initializing 368 
creating 368 
PrintDC data member 
TPreviewPage 355 
printdia.h 22 
printer banding flags 375 
printer constants 41 | 
printer string ID constants 44 
printer.h 22 
printers 356, 369 
changing 369 
configuring 367, 370 
default 
returning 368, 369 
updating 371 
device 
changing 371 
clearing 369 
errors, reporting 370 
IDs 41 
settings, initializing 368 
status, determining 44 
PrintExtent data member 
TPreviewPage 355 
printing 367, 373 
device handle 375 
discontinuing 370, 372 
errors, reporting 370 
events, responding to 369 
jobs, labeling 372 
multiple pages 374 
objects 537, 567 
selected pages 374 
specifications 
copying 368 
initializing 368 
page size 375 
Printout data member 
TPreviewPage 355 
printouts, banding 374, 375 
PrintPage member function 
TPrintout 374 
PrnDC data member | 
TPrintPreviewDC 379 
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PrnFont data member 
TPrintPreviewDC 379 
ProcessAppMsg member 
function 
TApplication 60 
ProcessCmdLine member 
function 
TRegistrar 656 
procinstance 690 
profile files 379 
progid registration key 572 
programs, current state 413, 415 
prompt data member 
TInputDialog 255 
properties 
automation servers and 545, 
559, 560 
documents 183, 1 188 
views 183 
property attributes, constants 48 
Property enum 184, 452 
property indexes 212 
property lists, retrieving 
handles 471 
PropertyCount member function 
TDocument 187 
TStorageDocument 419 — 
TView 453 
PropertyFlags member function 
TDocument 187 | 
TFileDocument 212 
TStorageDocument 419 
TView 453 | 
PropertyName member function 
TDocument 187 | 
TFileDocument 213 _ 
TStorageDocument 419 
TView 453 
protected constructors 
TCreatedDC 120 
protected data members 
TApplication class 61 
TButton class 73 
TButtonGadget 76 
TButtonGadgetEnabler 
class 80 
TCelArray class 82 
TChooseFontDialog class 89 
TClipboard class 96 
TClipboardViewer class 97 
TColor class 101 © 
TComboBoxData class 108 
TCommandEnabler class 112 
TCommonDialog class 113 
TControlGadget class 116 
TDC class 158 
TDecoratedFrame class 161 


TDib class 174 
TDocument class 189 
TEdit class 198 
TEditView class 207 
TFileDocument class 213 
TFilterValidator class 215 
TFindReplaceDialog 

class: 217 
TFrameWindow class 225 
TGadget class 232 
TGadgetWindow class 239 
TGauge class 244 
TGdiObject class 248 
TLayoutWindow class 264 
TListView class 273 
TMemoryDC class 287 
TMenu class 292 
TMenuDescr class 297 
TMenultemEnabler class 298 
TMessageBar class 300 
TMetaFilePict class 303 
TModule class 309 
TOpenSaveDialog class 343 
TPreviewPage class 355 
TPrintDC class 363 
TPrintDialog class 368 
TPrinter class 370 
TPrintout class 375 
TPrintPreviewDC class 379 
TPXPictureValidator 

class 382 
TRangeValidator class 384 
TSlider class 404 
TStatusBar class 415 
TStream class 421 
TStringLookupValidator 

class 422 
TTextGadget class 423 
TTinyCaption class 425 
TToolBox class 431 
TValidator class 439 
TView class 454 
TWindowDLC class 497 


protected member functions 


TApplication class 62 
TBitmap class 68 
TBitmapGadget class 69 
TButtonGadget 77 
TCheckBox class 85 
TChooseColorDialog class 87 
TChooseFontDialog class 89, 
324. 
TClipboard Viewer class 97 
TComboBox class 106 
TCommonDialog class 113 
TControl class 118 
TControlBar class 116 
TControlGadget class 116 


TDC class 159 
TDecoratedFrame class 161 
TDecoratedMDIFrame 

class 162 
TDialog class 167 
TDib class 175 
TDocManager class 181 
TDocument class 189 
TEdit class 198 
TEditFile class 203 
TEditView class 207 
TEventHandler class 209 
TFileDocument class 213 
TFindDialog class 216 
TFindReplaceDialog - 

class 217 
TFloatingFrame class 220 
TFrameWindow class 226 
TGadget class 233 
TGadgetWindow class 241 
TGauge class 245 
TGdiObject class 248 
THsSlider class 406 
TInputDialog class 256 
TLayoutWindow class 264 
TListBox class 270 
TListView class 274 
TMDI!IChild class 280 
TMbD!Client class 283 
TMDIFrame class 286 
TMenu class 292 
TMenuDescr class 298 
TMessageBar class 300 
TOleWindow class 330 
TOpenSaveDialog class 343 
TPalette class 350 
TPreviewPage class 355 
TPrintDialog class 369 
TPrinter class 371 
TPrinterAbortDlg class 372 
TPrintPreviewDC class 379 
TRadioButton class 383 _ 
TReplaceDialog class 388 
TScrollBar class 394 
TSlider class 401 
TStatic class 412 
TStatusBar class 415 
TTextGadget class 423 
TTinyCaption class 426 
TToolBox class 432 
TVbxControl class 446 
TView class 454 
TVSlider class 407 


protection flags 188 
Ps data member 


TPaintDC 347 


PtIn member function 


TGadget 234 


PtVisible member function 


TDC 147 


public data members 


TApplication class 55 
TButton class 72 
TCheckBox class 83 
TChooseColorDialog class 86 
TChooseColorDialog 
class::[Data 87 
TClipboard class 93 
TColor class 99 
TComboBox class 102 
TCommandEnabler class 111 
TDialog class 164 
TDocManager class 177 
TDocument class 183 
TEditFile class 202 
TEditSearch class 204 
TEventHandler class 209 
TEventHandler::TEventInfo 
class 210 
TFindReplaceDialog::TData 
class 218 
TFrameWindow class 223 
TGadget class 229 
TGroupBox class 251 
TInputDialog class 255 
TLayoutConstraint struct 257 
TLayoutMetrics class 259 
TListBoxData struct 270 
TListView class 272 
TMD!Client class 281 
TModule class 304 
TOleWindow class 329 
TPrintDialog::TData 364 
TResponseTableEntry 
class 388 
TScrollBar class 391 
TScrollBarData struct 394 
TScroller class 395 
TStatic class 410 
TStatus class 412 
TView class 452 | 
TWindowAttr struct 495 


public member functions 


TApplication class 57 
TBitmap class 66 
TBitmapGadget class 69 © 
TBitSet class 69, 70 
TButtonGadget 75 
TButtonGadgetEnabler 

class 80 
TCelArray class 81 
TCheckBox class 84 
TChooseColorDialog class 86 
TChooseFontDialog class 324 
TClipboard class 93 
TColor class: 100 
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TComboBox class 102. 
TComboBoxData class 107 
TCommandEnabler class 111 
TCommonDialog class 113 
TControlBar class 115 
TCursor class 121 
TDC class 123 
TDecoratedFrame class 160 
TDialog class 164 
TDib class 170 
TDocManager class 177 
TDocTemplate class 679 
TDocTemplateTD,V class 684 
TDocument class 184 
TDocument::List class 190 
TDropInfo class 685 
TEdgeConstraint struct 190 
TEdit class 193 © 
TEditFile class 202 | 
TEditSearch class 205 
TEditView class 206 
TFileDocument class 211 
TFileOpenDialog class 214 
TFileSaveDialog class 214 
TFilterValidator class 215 
TFindReplaceDialog 
class 217 

TFloatingFrame class 220 
TFont class 222 

— TFrameWindow class 223 
TGadget class 230 
TGadgetWindow class 236 
TGauge class 243 
TGdiObject class 246 
TGroupBox class 251 
TIcon class 255 
TInputDialog class 256 
TLayoutWindow class 263 
TListBox class 265 
TListBoxData struct 271 
TListView class 273 
TLocaleString 277 
TLookupValidator class 278 
TMD!IChild class 279 
TMD!Client class 281 
TMDIFrame class 285 
TMemoryDC class 287 
TMenu class 288 
TMenuDescr class 296 
TMenultemEnabler class 299 
TMessageBar class 299 
TMetaFilePict class 302 
TModule class 304 
TOleWindow class 327 
TOpenSaveDialog class 342 
TPalette class 348 
TPen class 352 
TPoint class 687 


TPointer<> class 689 
TPopupMenu class 353 
TPreviewPage class 355 
TPrintDC class 356 
TPrintDialog class 368 
TPrintDialog::TData 
struct 366 
TPrinter class 369 
TPrintout class 373 
TPrintPreviewDC class 376 
TPXPictureValidator 
class 380 
TRangeValidator class 388 
TRect class 
691 
TRegion class 385 
TResId class 697 
TScrollBar class 392 
TScroller class 396 
TSeparatorGadget class 399 
TSize class 698 
TSlider class 400 
TStatic class 411 
TStatusBar class 414 
TStream class 420 
TStringLookupValidator 
class 421 
TTextGadget class 423 
TToolBox class 431 
TUlHandle class 435 
TValidator class 437 
TVbxControl class 442 
TView class 452 
TWindow View class 498 
public structures 
TGadget class 229 
PumpWaitingMessages member 
function 
TApplication 60 
pushbuttons 72,73 
default 73 


Q 


Query Abort member function 


TPrintDC 362 
QueryCreate member function 
TClipboard 95 | 
QueryEscSupport member 
function 7 
TPrintDC 363 
QueryLink member function 
TClipboard 96 
QueryObject member function. 
TUnknown. 660 
QueryThrow member function 
TApplication 60 
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QueryViews member function 
TDocument 188 


R 


radio buttons 382 
button state 28 
selection box state 28 
radiobut.h 22 
Range data member 
TSlider 404 
range validators 383 
ranges 
converting to scroll values 46 
numeric, testing for 383 
Read member function 
TDib 176 
TEditFile 203 
TOleDocument 313 
reading See loading 
RealizePalette member function 
TDC 147 _ 
ReceiveMessage member 
function 
TWindow 479 
Reconstruct member function 
TTHatch8x8Brush 253 
Record member function 
TAutoCommand 576 
Rectangle member function 
TDC 147 
rectangles 690 
height and width 698 
RectVisible member function 
TDC 147 
Red member function 
TColor 101 
RedrawWindow member 
function 
TWindow 479 
RefAdd member function 
TGdiObject 247 | 
RefCount member function 
TGdiObject 247 
RefDec member function 
TGdiObject 247 
RefFind member function 
TGdiObject 247 
Reflnc member function 
TGdiObject 247 
RefRemove member function 
TGdiObject 247 
Refresh member function 
TVbxControl 444 
RefTemplate member function 
TDocManager 181 


-REGDATA macro 675. 


REGDOCFLAGS macro 678 
REGFORMAT macro 676 
REGICON_ macro 678 
regions 384 
Register member function 
TWindow 480 
RegisterAppClass member 
function 
TRegistrar 656 
RegisterClass member function 
TOcApp 604 
RegisterClasses member 
function 
TOcApp 604 
RegisterClipboardFormat 
member function 
TClipboard 96 
RegisterClipFormats member 
function 
TOcView 648 
RegisterHotKey member 
function 
TWindow 480 
registering Clipboard 
formats 567, 601, 603 
registering ObjectComponents 
applications 529 
registers, this parameter 50 
registrar objects 634, 653 
registration 
verifying 634 
Windows 480 
registration class names 74, 200, 
270, 284 | 
registration classes overview 16, 
672 
registration databases 529 
registration keys 529 
automated objects 665, 666 
automation classes, 
identifying 572 
Clipboard 561 
debugging servers 549-551 
default file formats 561 
description 553 
directory 554 
directory paths 561, 571 
document filters 554 
file-name extensions 560 
globally unique 
identifiers 548 
Help files 562, 665 
icons 563 
locale IDs 564 
OLE applications 549 
server names 564 


servers 563 
concurrent usage 570, 665 
version 666 
viewing objects 536-538 
registration macros 673, 674, 
675, 676, 677, 678, 679 
registration tables 548 
constructing 533 
description strings 553 
REGISTRATION FORMAT 
_BUFFER_macro 679 
REGITEM_macro 676 
REGSTATUS_ macro 677 
REGVERBOPT macro 678 
relational databases 
validity checking 380 
Relationship data member 
TLayoutConstraint 257 
Release data member 
TOcSaveLoad structure 640 
ReleaseCapture member 
function 
TWindow 480 
ReleaseDataObject member 
function 
TOcInitInfo 620 
ReleaseDoc member function 
TOleDocument 313 
TStorageDocument 419 
ReleaseGlyphDib member 
function 
TButtonGadget 79 
ReleaseObject member function 
TOcApp 605 
TOcView 648 
RelWin data member 
TLayoutConstraint 258 
Remove member function 
TAppDictionary class 55 
TDocument::List 190 
TGadgetWindow 238 
RemoveChild member function 
TWindow 493 
RemoveChildLayoutMetrics 
member function 
TLayoutWindow 264 
Removed member function 
TControlGadget 117 
TGadget 234 
Removeltem member function 
TVbxControl 445 
RemoveMenu member function 
TMenu 292 
RemoveProp member function 
TWindow 480 
removing a property 480 


Rename member function 
TOcPart 629 | 
TOcRemView 639 
TOcView 648 

RenameParts member function 
TOcDocument 611 

ReOrg member function 
TPrintPreviewDC 376 

Repeat data member 
TButtonGadget 77 

ReplaceWith data member 
TFindReplaceDialog::TData 

219 | 

ReplaceWith member function 
TEditFile 203 

Report member function 
TAutoCommand 576 

ReportError member function 
TPrinter 370 

REQUIRED ARG macro 573 

ReScale member function 
TPrintPreviewDC 376 

ResetDC member function 
TDC 147 

ResetSelections member function 
TComboBoxData 107 
TListBoxData 272 

ResId data member 
TButtonGadget 77 
TXOwl 503 

ResizePalette member function 
TPalette 349 

resource files 23 

resource IDs 
accelerator keys 41 
input dialog box 40 
mode constants 42 
printer 41 
retrieving default 166 
string ID constants 42 
string, converting to 250 

ResourceldToString member 

function 
TXOwl 504 

resources 276 
callback functions and 309 
finding 304, 305 
handles, returning 308 
loading 309 

into memory 305, 308, 309 
size, returning 309 

response table entries 388 
finding entries 208 

response tables 87 
declaring 31 
defining 32, 35 : 
document manager and 17 
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Restart member function 
TOcFormatListlter 616 
TOcPartCollectionIter 634 

RestoreBitmap member function 
TMemoryDC 287 

RestoreBrush member function 
TDC 148. 

RestoreDC member function 
TDC 148 

- RestoreFont member function 
TDC 148 | 
TPrintPreviewDC 377 

RestoreMemory member 

function 
TModule 309 | 

RestoreMenu member function 
TFrameWindow 224 

RestoreObjects member function 
TDC 148 
TMemoryDC 287 

RestorePalette member function 
TDC 148 | 

RestorePen member function 
TDC 148 

RestoreTextBrush member 

function 
TDC 148 

ResumeThrow member function 
TApplication 60 

retrieving data 568 

return codes, OLE 562 

Return member function 
TAutoCommand 576 
TAutolterator 582 

returning pointers 40, 470 

Revert member function 
TDocument 188 
TFileDocument 213 
TStorageDocument 419 

Rgb member function 
TColor 101 

RGBOUAD struct 733 

RGBTRIPLE struct 733 

RightOf member function 
TEdgeConstraint 191 

root documents 188 

~RootDocument member function 
TDocument 188 

RoundRect member function 
TDC 148 © 

RT ACCELERATOR 

constant 306 

RT_BITMAP constant 306 

RT_ CURSOR constant. 306 

RT_DIALOG constant 306 

RT_FONT constant 306 


~ RT_FONTDIR constant 306 


RT_ICON constant 306 
RT MENU constant 306 
RT_RCDATA constant 306 
RT_STRING constant 306 
Run member function 
TApplication 60 
TRegistrar 656 


S 


SameAs member function 
TEdgeConstraint 191 
TEdgeOrSizeConstraint 192 

sample classentry 25 

sample programs 
caption bars 425 
data validation objects 436 
sliders 399 


~ Save member function ~ 


TEditFile 202, 203 
~ TOcPart 630 
TOcRemView 639 
SaveAs member function 
TEditFile 202, 203 
SaveDC member function 
TDC 149 
SaveParts member function 
TOcDocument 611 
SaveToFile member function 
TOcDocument 612 
saving documents 189 
saving compound 
documents 609 
path 188 
saving objects 566, 630, 639 
~ compound documents 611, 
612 
SB_BOTH constant: 51 
SB_BOTTOM constant 392 
SB_CTL constant 51, 471 
SB_HORIZ constant 51 
SB_HORZ constant 471 
SB_LINEUFP constant 393 
SB_VERT constant 51, 471 
SBBottom member function 
TScrollBar 392 
SBLineDown member function 
TScrollBar 392 
SBLineUp member function 
TScroliBar 393 
SBPageDown member function 
TScrollBar 393 
SBPageUp member function 
TScrollBar 393 | 
SBS_HORZ constant 391 
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SBS_VERT constant 391 
SBThumbPosition member 
function — 
TScrollBar 393 
SBThumbTrack member 
function 
TScrollBar 393 
SBTop member function 
TScrollBar 393 
Scale data member 
TOleWindow 330 
ScaleViewportExt member 
function . 
TDC 149 
TPrintPreviewDC 377 
ScaleWindowExt member 
function 
TDC 149 
TPrintPreviewDC 377 
scaling windows 311, 640 
scope resolution operator 
Windows API calls 3 
screen devices 
logical point 
conversions 376, 377 
screen resolution 258 
ScreenToClient member function 
TWindow 480 
scroll bars 391, 394 
constants 51 
modes 51 
line down position 392 
range, getting 392 
sliders vs. 399 
thumb positions 391, 392, 
393, 394 
transferring 394 
values, converting 46 
warning, 391 
Scroll member function 
TEdit 196 
scrollba.h 22 
ScrollBy member function 
TScroller 398 
ScrollIDC member function 
TDC 149 
scroller 456 
Scroller data member 
TWindow 456 
scroller.h 22 
scrolling windows 311, 642 
ScrollTo member function 
TScroller 398 
ScrollWindow member function 
TOcView 648 
TWindow 481 


ScrollWindowEx member 
function 
TWindow 481 
SDPtoLP member function 
TPrintPreviewDC 377 
Search member function 
TEdit 197 
SearchCmd data member 
TEditSearch 204 
SearchData data member 
TEditSearch 204 
SearchDialog data member 
TEditSearch 204 
SearchEntries member function 
TEventHandler 209 
searches 204 
case and 197 
list box 266 
specific strings 279, 422 
SelCount data member 
TListBoxData 270 
select and restore functions 376, 
377 
Select member function 
TComboBoxData 108 
TListBoxData 272 
TOcPart 630 
TOleWindow 340 
SelectAll member function 
TOcPartCollection 633 
SelectAnySave member function 
TDocManager 181 
SelectClipPath member function 
TDC 150 
SelectClipRgn member function 
TDC 150 
SelectDocPath member function 
TDocManager 181 
SelectDocT ype member function 
TDocManager 182 
SelectEmbedded member 
function 
TOleWindow 340 
SelectImage member function — 
TBitmapGadget 69 
selection 
colors 86 
data transfer 271 
number of items 270 
text 195, 197 
Selection data member 
TComboBoxData 108 
SelectionChanged member 
function 
~TGroupBox 252 
SelectObject member function 
TDC 150 


TMemoryDC 287 
TPrintPreviewDC 377 
SelectSave member function 
TDocManager 181 
TDocTemplate 682 
SelectStockObject member 
function 
TDC 150 
TPrintPreviewDC 377 
SelectString member function 
TComboBoxData 108 
TListBoxData 272 
SelectViewType member 
function 
TDocManager 182 
SelIndex data member 
TComboBoxData 108 
Selindices data member 
TListBoxData 270 
SelStrings data member 
TListBoxData 270 
SendDlgltemMessage member 
function 
TWindow 481 
SendDigltemMsg member 
function 
TDialog, obsolete 167 
sending messages 459 
SendMessage member function 
TWindow 481 
SendNotification member 
function 
TWindow 481 
separators 399 
servers | 
compound documents 
and 609 
debugging 549 
embedded object classes 637 
names, registering 564 
passing data 568 
registering 563 
single-use and multiuse 570, 
665 
Set member function 
TEdgeConstraint 191 
TRect 695 
SetAbortProc member function 
TPrintDC 363 
SetActive member function 
TOcPart 630 
SetActiveView member function 
TOQcDocument 612 
SetActiveWindow member 
function 
TWindow 481 


SetAntialiasEdges member 
function 
TButtonGadget 76 
SetBitmapBits member function 
TBitmap 67 
SetBitmapDimension member 
function 
TBitmap 67 
SetBkColor member function 
TDC 151 
TPrintPreviewDC 378 
SetBkgndColor member function 
TWindow 482 
SetBkMode member function 
TDC 151 
SetBorders member function 
TGadget 231 
SetBorderStyle member function 
TGadget 231 
SetBounds member function 
TBitmapGadget 69 
TButtonGadget 79 
TControlGadget 117. 
TGadget 231 
SetBoundsRect member function 
TDC 151 | 
SetBrushOrg member function 
TDC 151 — | 
SetButtonState member function 
TButtonGadget 76 
SetButtonType member function 
TButtonGadget 75 
SetCaption member function 
TDialog 167 
TWindow 482 
SetCapture member function 
TWindow 482 
SetCaretBlinkTime member 
function 
TWindow 482 
SetCaretIndex member function 
TListBox 268 
SetCaretPos member function 
TWindow 482 
SetCelSize member function 
TCelArray 81 
SetCheck member function 
TButtonGadgetEnabler 80 
TCheckBox 84 
TCommandEnabler 112 
TMenultemEnabler 299 
SetChildLayoutMetrics member 
function 
TLayoutWindow 264 
SetClassLong member function 
TWindow 482 
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SetClassWord member function 
TWindow 482 -. 
SetClientWindow member 
function 
TDecoratedFrame 161 
TFrameWindow 224 
SetClipboardData member 
function 
TClipboard 96 
SetClipboardViewer member 
function 
TClipboard 96 
SetColor member function 
TDib 173 
TGauge 243 
SetColumnWidth member 
function . 
TListBox 268 
SetCommandHook member 
function 
TAutoCommand 576 
SetCopyCount member function 
TPrintDC 363 
SetCursor member function 
TWindow 483 
SetDefaultExt member function 
TDocTemplate 682 
SetDefaultId member function 
TDialog 167 
SetDevMode member function 
TPrintDialog::TData 367 
SetDevNames member function 
TPrintDialog::TData 367 
SetDIBits member function 
TDC 151 
SetDIBits ToDevice member 
function 
TDC 152 
SetDirection member function 
TGadgetWindow 238 
TToolBox 431 
SetDirectory member function 
TDocTemplate 682 
SetDlgItem member function 
TWindow 483 : 
SetDlgItemText member 
function 
TWindow 483 
setDocManager member 
function — 
TApplication 63 
TDocTemplate 682 
SetDocmanager member | 
function 
TDocument 188 


SetDocPath member function 
TDocument 188 
TStorageDocument 419 

SetDocTitle member function 
TEditView 207 
TFrameWindow 225 
TListView 273 
TOleView class 324 
TView 453 
TWindow 483. 
TWindowView 499 

SetEditSel member function 
TComboBox 105 

SetEmbedded member function 
TDocument 188 

SetEmpty member function 
TRect 696 

SetEnabled member function 
TGadget 231 

SetErrorMsgHook member 

function 
TAutoCommand 576 

SetExtendedUI member function 
TComboBox 105 

SetExtent member function 
TListView 275 

SetFileFilter member function 
TDocTemplate 682 

SetFileName member function 
TEditFile 203 

SetFilter member function 
TOpenSaveDialog::TData 346 

SetFlag member function 
TAutoCommand 576 
TDocTemplate 682 
TWindow 483 

SetFocus member function | 
TWindow 484 

SetHandle member function 
TEdit 197 

SetHintCommand member 

function 
TGadgetWindow 239 

SetHintMode member function 
TGadgetWindow 239 

SetHintText member function 

_. TMessageBar 300 

SetHorizontalExtent member 

function. 
TListBox 268 

SetHost member function 
TOcPart 630 

SetIlcon member function 
TFrameWindow 225 

SetIndex member function — 
TDib 173 
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SetInstance member function 
TModule 309 
SetItemData member function 
TComboBox 105 
TListBox 268 
SetItemHeight member function 
TComboBox 105 
TListBox 268 
SetItemRect member function 
TListBox 268 
SetLang member function 
TAutoProxy 589 
SetLed member function 
TGauge 243 
SetLink member function 
TOcView 649 
SetMainWindow member 
function 
TApplication. 63 
SetMapMode member function 
TDC 152 
TPrintPreviewDC 378 
SetMapperFlags member 
function 
TDC 152 
SetMappingMode member 
function. 
TMetaFilePict 303 
SetMargins member function 
TFloatingFrame 220 
TGadget 231 
TGadgetWindow 239 
SetMenu member function 
TFrameWindow 225 
TMDI{IFrame 286 
TWindow 484 
SetMenuDescr member function 
TFrameWindow 225 
SetMenultemBitmaps member 
function 
TMenu 292 
SetMiterLimit member function 
TDC 152 
SetModelndicator member 
function 
TStatusBar 414 
SetModule member function 
TDocTemplate 683 
TMenuDescr 297 
TWindow 484 
SetName member function 
~TModule 309 
TOcDocument 612 
SetNext member function | 
TWindow 484 


SetNotchCorners member 
function 
TButtonGadget 76 
SetNull member function 
TRect 696 
SetNumCels member function 
TCelArray 82 
SetOcApp member function 
TOleFrame 317 
SetOcDoc member function 
TOleDocument 314 
SetOffset member function 
TCelArray 82 
SetOpenMode member function 
TDocument 188 
SetOption member function 
TOcApp 605 
TRegistrar 657 
TValidator 438 
SetOuter member function 
TUnknown 659 
SetPageNumber member 
function 
TPreviewPage 355 
SetPageSize member function 
TScroller 397 
SetPaletteEntries member 
function 
TPalette 349 
SetPaletteEntry member function 
TPalette 350 
SetParent member function 
TWindow 484 
SetPasswordChar member 
function, TEdit 197 
SetPixel member function 
TDC 153 
SetPolyFillMode member 
function, TDC 153 
SetPos member function 
TOcPart 631 
SetPosition member function 
TScrollBar 393 
TSlider 400 
SetPrinter member function 
TPrinter 371 
SetPrintParams member function 
TPrintout 374 
SetProp member function 
TVbxControl 445 
TWindow 484 
SetProperty member function 
TDocument 188 
TFileDocument 213 
TStorageDocument 419 
TView 454 


SetpWindow member function 
TVbxControl 446 
SetRange member function 
TGauge 244 
TScrollBar 393 
TScroller 397 
TSlider 400 
SetReadOnly member function 
TEdit 197 
SetRect member function 
TEdit 197 
SetRectNP member function 
TEdit 197 
SetRectkgn member function 
TRegion 387 
SetRedraw member function 
TWindow 484 
SetResourceHandler member 
function 
TModule 309 
SetRGBColor member function 
TChooseColorDialog 86 
SetRGBMseld data member 
TChooseColorDialog 87 
SetROP2 member function 
TDC 153 
SetRuler member function 
TSlider 400 
SetSBarRange member function 
TScroller 397 
SetScale member function 
TOcScaleFactor 642 
TOleWindow 340 
SetScrollPos member function 
TWindow 485 
SetScrollRange member function 
TWindow 485 
SetSel member function 
TListBox 268 
SetSelection member function 
TEdit 197 
TOleWindow 340 
SetSellndex member function 
TComboBox 105 
TListBox 269 
SetSelIndexes member function 
TListBox 269 | 
SetSelltemRange member 
function, TListBox 269 
SetSelString member function 
TComboBox 105 
TListBox 269 
SetSelStrings member function 
TListBox 269 
SetShadowStyle member 
function 
TButtonGadget 76 


SetShrinkWrap member function 
TGadget 232 
TGadgetWindow 239 

SetSize member function 
TGadget 232 
TMetaFilePict 303 
TOcPart 631 

SetSpacing member function 
TStatusBar 414 

SetState member function 
TCheckBox 84 

SetStorage member function 
TOcDocument 612 
TOleDocument 314 
TStorageDocument 420 

SetStretchBltMode member 

function 
TDC 153 

SetStyle member function 
TCheckBox 84 

SetSymbol member function 
TAutoCommand 576 
TAutolterator 582 


_ SetSysColors member function 


TColor 101 
SetSysModalWindow member 
function 
~ TWindow 485 
SetSystemPaletteUse member 
function 
TDC 154 
SetTabStops member function 
TEdit 197 
TListBox 269 
SetTemplate member function 
TDocument 189 
SetText member function 
TButtonGadgetEnabler 80 
TComboBox 105 
TCommandEnabler 112 
TMenultemEnabler 299 
TMessageBar 300 
TStatic 411 
TTextGadget 423 
SetTextAlign member function 
TDC 154 
SetTextCharacterExtra member 
function 
TDC 154 
SetTextColor member function 
TDC 154 
TPrintPreviewDC 378 
SetTextJustification member 
function 
TDC 154 
SetTimer member function 
TWindow 485 
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setting bits 69 ; 
SetTitle member function 
TDocument 189 
SetTopIndex member function 
TListBox 269 
SetTransferBuffer member 
function, TWindow 485 
SetUnits member function 
TScroller 397 
Setup member function 
TPrinter 370 
SetupDC member function 
— TOleWindow 340 
SetupThumbRgn member 
function 
TSlider 403, 405 
SetupWindow member function 
TButton 74 
TClipboardViewer 98 
~TComboBox 106 
TCommonDialog 114 
TDecoratedFrame 161 
TDialog 168 
TEdit 201 
TEditFile 204 
TEditSearch 205 
TFrameWindow 227 
TInputDialog 256 
TOcApp 605 
TOcView 649 
TOleFrame 320 
TOleWindow 340 
TPrinterAbortDlg 372 
TScrollBar 394 
TSlider 403 
TWindow 493 
SetUserAbort member function 
TPrinter 370 
SetValidator member function 
TEdit 197 
SetValue member function 
TGauge 244 
SetVBXProperty member 
function 
TVbxControl 446 
SetViewMenu member function 
TView 454 | 
SetViewportExt member 
function | 
TDC 154 
TPrintPreviewDC 378 
SetViewportOrg member 
function, TDC 155 
SetVisible member function 
— ‘TOcPart 631 
SetWindow member function 
TScroller 398 


SetWindowExt member function 
 TDc 155 
TPrintPreviewDC 378 


~ SetWindowFont member 


function, TWindow 485 
SetWindowLong member | 
function, TWindow 485 


_ SetWindowOrg member 


function, TDC 155 
SetWindowPlacement member 
function, TWindow 486 
SetWindowPos member function 
TWindow 486 
SetWindowText member 
function, TWindow 486 
SetWindowWord member 
function, TWindow 487 
SetWinMainParams member 
function, TApplication 61 
SetWordBreakProc member 
function, TEdit 198 
SetWorldTransform member 
function, TDC 155 
ShadowStyle data member 
TButtonGadget 77 
ShareViMsgld data member 
_TOpenSaveDialog 343 
ShareViolation member function 
TOpenSaveDialog 344 
shCompat constant 51 
shDefault constant 51 
shMask constant 51 
shNone constant 51 
short far*() operator 
TAutoVal 597 
short types 590 
short() operator 
TAutoVal 597 
ShouldDelete data member 
TCelArray 82 
TDC 159 
~ TGdiObject 248 
TMenu 292 
Show data member 
TOcTooiBarInfo | 
structure 643 — 
Show member function 
TOcPart 631 
TWindow 487 | 
ShowCaret member function 
TWindow 487 
showCmd constants 487 
Show List member function 
TComboBox 105 
ShowObjects data member 
TOleWindow 330 
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ShowOwnedPopups member 
function, TWindow 487 
ShowScrollBar member function 
TWindow 487 
ShowWindow member function 
TMDIChild ‘280 
-TWindow 487 
shRead constant 51 
shReadWrite constant 51 
shrinkToClient parameter 222, 


pee 


ShrinkWrapHeight data member 
TGadget 232 
TGadgetWindow 240 

shrink-wrapping gadgets 236 

ShrinkWrapWidth data member 
TGadget 233 
TGadgetWindow 240 

Shutdown member function 
TRegistrar 657 

ShutDownWindow member 

function 
~ TWindow 487 

shWrite constant 51 

signatur.h 22 

single-use servers 570, 665 

SiteSize member function 
TOcScaleFactor 641 

size constraints, creating 

windows 258 

Size member function 
TDib 173 
TMetaFilePict 303 
TRect 696 
TUlHandle 436 

SizeMax data member 
TChooseFontDialog::TData 91 

SizeMin data member 
TChooseFontDialog::TData 91 

SizeOfResource member 

function | | 
TModule 309 


— slicing bitmaps 80 


SlideDC data member 
TSlider 404 


slider.h 23 


sliders 399 
background colors 402 
storing 404 
background, erasing 401 
horizontal 405 
objects 
constructing 400 
destructing 400 
painting 401, 403 
entire 402 
rulers in 403 


thumbs 403 
recalculating sizes 402 
resource ID 

thumb knob 405 
thumb positions 

aligning with tick 
positions 399, 400 

current 400 

moving 400, 401, 403 

present range 400 

returning 404 

setting 402 

snapping 404, 405 

translating 403 
thumb hace defining 403, 

405 
tick positions and 399 
setting gaps 405 
vertical 407 
SlideThumb member function 
TSlider 403 
Sliding data member 
TShder 404 
SlotThick data member 
TSlider 404 
Snap data member 
TSlider 405 
snapping 404, 405 
SnapPos member function 
TSlider 404 
sounds, beep 200 
Spacing data member 
TStatusBar 415 
SS_LEFT constant 411 
stack, automation 
commands 590, 594. 
StartDoc member function 
TPrintDC 363 
StartPage member function 
TPrintDC 363 
StartScan member function 
TDib 174 


StashContainerPopups member 


function 
~ TOleFrame 320 
StashCount data member 
TOleFrame 320 
StashedContainerPopups data 
member, TOleFrame 320 
Stat data member, TXOle 664 
State data member 
TButtonGadget 77 
static controls 
registration class name 412 
resources and associating 
with objects 411 
text length 410 


static text interface element 410 
statich 23 
StaticName member function 
TEditView 207 
TListView 273 
TOleView class 324 
TWindowView 499 
status, main window 304 
status bars 413 
borders 415 
creating 413, 414 
inserting text in 414 
spacing items in 414, 415, 416 
Status data member 
TModule 304 
TWindow 456 
status lines 159 
statusba.h 23 
Step member function 
TAutoEnumerator 580 
TAutolterator 582 
stgdoc.h 23 
Storage data member 
TOcInitInfo 619 
Storagel data member 
TOcSaveLoad structure 640 
TStorageDocument 420 
storages 609 
streaming 
~ TFileDocument 212 
TInStream 256 
TOutStream class 346 
streams 212 
documents 48, 189 
StretchDIBits member function 
TDC 155, 156 
string resources, localizing 276 
string() operator 
TAutoVal 597 
string-lookup validators 421 
strings 
automated objects 592 
checking validity of 421 
comparing 215, 266, 278 
picture 380 
concatenating 271 
deleting 265 
finding 271 
getting 267 
ID constants 42 
list view 44 
inserting 268 
length 410 
getting 267 
list boxes 265, 270, 271 
loading into memory 308 
resource [Ds 250 


retrieving 271, 272 
searching for 279, 422 
Strings data member 
TComboBoxData 108 
TListBoxData 270 
TStringLookupValidator 422 
StrokeAndFillPath member 
function 
TDC 156 
StrokePath member function 
TDC 156 
structs 
DOCINFO 363 
TBandInfo 65 
Style data member 
TChooseFontDialog::TData 91 
TWindowAttr 495 
styles 
combo boxes 102 
edit controls 192 
list box 265 
scroll bars 391 
SubclassWindow Function 
member function 
TWindow 488 
support classes 15, 671 
SuspendThrow member function 
TApplication 61 
SW_HIDE constant 56 
SW_MINIMIZE constant 56 
SW_SHOW constant 56 
SW_SHOWDEFAULT 
constant 56 
SW_SHOWMAXIMIZED 
constant 56 
SW_SHOWMINIMIZED 
constant 56 
SW_SHOWNA constant 56 
SW_SHOWNOACTIVATE 
constant 56 
SW_SHOWNORMAL 
constant 56 
SW_SHOWSMOOTH 
constant 56 
Symbol data member 
TAutoCommand 577 
SyncFont member function 
TPrintPreviewDC 379 
synchronizing functions 376, 379 
SysColorChange member 
function 
TBitmapGadget 69 
TButtonGadget 76 
SyscolorChange member 
function 
TGadget 232 
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system and model settings for 
compiling 17 
_ System menu, creating 422 


T 


T typedef 389 
T& () operator 
~~ TAutoObject 585 
T*() operator 
TAutoObject 585 
TPointer<> 689 
tab stops | 
creating 251 
edit controls, setting 197 
TabbedTextOut member 
function 
TDC 156 
TActionFunc typedef 51 
TActionMemFunc typedef 51 
Tag data member 
TDocument 183 
TView 452 
tagSize structure 697 
TAlign member function 
TTextGadget 424 
TAnyDispatcher typedef 52 
TAnyPMEF typedef 51 
TAppDictionary class 52 
member functions 
Add 54 
Condemn 54 
DeleteCondemned 54 
GetApplication 54 
Iterate 55 
Remove 55 
typedefs 53 
TApplication class 55 
constructors 56 
data members 
BreakMessageLoop 61 
cmdShow 56 
HAccTable 55 
HPrevInstance 55 
_ MessageLoopResult 61 
destructor 57 
member functions 
BeginModal 57 
BWCCEnabled_ 57 
CanClose 57 
Condemn. 58 
Ctl3dEnabled 58 | 
EnableBWCC 58 
EnableCtl3d 58 © 
EnableCtl3dAutosubclass 
58 
EndModal 58 
Find 58 


GetBWCCModule 59 
GetCtl3dModule 59 
GetDocManager 59 
GetMainWindow 59 
GetWindowPtr 59 _ 
GetWinMainParams 59 
IdleAction 62 
InitApplication 62 
InitInstance 62 
InitMainWindow 62 
MessageLoop 59 
PostDispatchAction 59 
PreProcessMenu 60 
ProcessAppMsg 60 


PumpWaitingMessages 60 


QueryThrow 60 — 
ReseTicw 60 
Run 60 
setDocManager 63 
SetMainWindow 63 
SetWinMainParams 61 
SuspendThrow 61 
TermInstance 63 
Uncondemn 61 
TApplication::TXInvalid- 
Window class 63 _ 
constructor 63 
member functions 
Clone 63 
Throw 63 
TAutoBase class 573 
destructors 573 
TAutoBool struct 574 
_data member 574 
TAutoCommand class 574 
constructor 574 
data members 
Attr 577 
Symbol 577 
destructor 574 
- member functions 
ClearFlag 575 
Execute 575 
~ Fail 575 
GetSymbol 575 
Invoke 575 
IsPropSet 575 
LookupError 575 
Record 576 
Report 576 
Return 576 
SetCommandHook 576 
SetErrorMsg 576 
SetFlag 576 
SetSymbol 576 
TestFlag 577 
Undo 577 
Validate 577 
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typedefs 
TCommandHook 574 
TErrorMsgHook 575 
TAutoCurrency far*() operator 
TAutoVal 598 7 
TAutoCurrency struct 577 
data member 577 
TAutoCurrency() operator 
TAutoVal 597 
TAutoDate far*() operator 
TAutoVal 598 
TAutoDate struct 578 
constructors 578 
data members 
ClassInfo 578 
Date 578 
member function 578 
TAutoDate() operator 
TAutoVal 598 
TAutoDelete enum 246 
TAutoDouble struct 578 
data member 578 
TAutoEnumerator<> class 579 
constructors 579 
destructor 579 
member functions 
Bind 579 
Clear 579 
Object 580 
Step 580 
Unbind 580 
Value 580 
TAutoFactory class 64 
member functions 
Create 64 
CreateApp 64 
DestroyApp 65 
TComponentFactory 65 
TAutoFloat struct 580 
data member 580 
TAutolterator class 581 
constructors 583 
data member 583 
member functions 
Copy 581 
GetSymbol 581 
Init 582 
Return 582 
SetSymbol 582 
Step 582 
Test 583 
operator 582 
TAutoLong struct 583 
data member 584. 
TAutoObject<> class 584 
constructors 584 


data member 585 
operators 584, 585 
TAutoObjectByVal<> class 585 
constructors 586 
operators 585 
TAutoObjectDelete<> class 586 
constructors 586 
member functions 
TObjectDescriptor 587 
operators 586 
TAutoProxy class 587 
constructor 589 
destructor 587 
member functions 
Bind 588 
[Dispatch 588 
Invoke 589 
IsBound 588 
Lookup 588 
MustBeBound 589 
SetLange 589 
Unbind 589 
operators 588 
TAutoShort struct 590 
data member 590 
TAutoStack class 590 
constructor 591 
data members 
ArgCount 591 
ArgSymbolCount 591, 592 
CurrentArg 591 
LanglId 592 
Owner 592 
destructor 591 
dispatch ID 592 
member function 591 
operator 591 
SetValue constant 592 
TAutoString struct 592 
constructors 592 
data member 594 
destructor 593 
operators 593 
TAutoType struct 594 
member function 594 
TAutoVal class 594 
member functions 
Clear 596 
Copy 596 
GetDataType 596 
IsRef 597 
operators 595, 597 
TAutoVoid struct 598 | 
data member 599 
TBandInfo struct 65 
TBitmap class 65 
constructors 65, 68 


member functions 
BitsPixel 66 
Create 68 
GetBitmapBits 66 
GetBitmapDimension 66 
GetObject 67 
Height 67 
Planes 67 
SetBitmapBits 67 
SetBitmapDimension 67 
ToClipboard 67 
Width 67 
operators 67, 68 
TBitmap&() operator 
TCelArray 81 
TBitmapGadget class 68 
constructor 68 
destructor 68 
member functions 
GetDesiredSize 69 
Paint 69 
SelectImage 69 
SetBounds 69 
SysColorChange 69 
TBitSet class 69 
constructors 69 
member functions 
Disableltem 70 
Enableltem 70 
Has 70 
IsEmpty 70 
operators 70, 71 
TBIVbxLibrary class 71 
constructor 71 
destructor 71 
TBool far*() operator 
TAutoVal 598 
TBool() operator 
TAutoVal 598 


TBorders struct 


TGadget class 229 
TBorderStyle enum 229 
TBrush class 71 

constructors 71 

member functions 

GetObject 72 
UnrealizeObicst 72 

operator 72 
TButton class 72 

constructors 73 

data members 

IsCurrentDefPB 73 
IsDefPB 73 
member functions 
BMSetStyle 73 
EvGetDlgCode 73 
GetClassName 74 
~ SetupWindow 74 


TButtonGadget class 74 
constructor 75 
data members 
AntialiasEdges 76 
BitmapOrigin 76 
ei 55 
NotchCorners 76 
Pressed 77 
Repeat 77 
ResId 77 
ShadowStyle 77 
State 77 
Type 77 
destructor 75 
member functions 
Activate 77 
BeeginPressed 77 
BusldCelA say Ti 
CancelPressed 78 
CommandEnable 75 
GetDesiredSize 78 
GetGlyphDib 78 
Invalidate 78 
LButtonDown 78 
LButtonUp 78 
MouseEnter 78 
MouseLeave 78 
MouseMove 79 
Paint 79 
ReleaseGlyphDib 79 
SetAntialiasEdges 76 
SetBounds 79 
SetButtonState 76 
SetButtonType 75 
SetNotchCorners 76 
SetShadowStyle 76 
SysColorChange 76 
TState 75 
typedefs 75 
TButtonGadgetEnabler class 79 
constructor 79 
data members | 
gadget 80 
member functions 
Enable 80 
SetCheck 80 
SetText 80 
TCelArray class 80 
constructors 80 
data members 
Bitmap 82 
CSize 82 
NCels 82 
Offs 82 
ShouldDelete 82 
destructor 81 
member functions 
CelOffset 81 
CelRect 81 
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CelSize 81 
“NumCels 81 
Offset 81 - 
~ SelCelSize 81 

SetNumCels 82 
SetOffset 82 
operators 81 
TCEnabled data member 
TTinyCaption 426 
TCharSet class 82 
~ constructors 82 
operator 83 
TCheckBox class 83 
constructors 83 
data members 
Group 83 
member functions 
BNClicked 85 
Check 84 
EvGetDlegCode 85 
GetCheck 84 
GetClassName 85 
GetState 84 
SetCheck 84 
SetState 84 
SetStyle 84 
Toggle 84 
Transfer 85 
Uncheck 85 


TChooseColorDialog class 86 


— constructor 86 
data members 
cc 86 
Data 87 
SetRGBMsegld 87 
member functions 
DialogFunction 87 
DoExecute 87 
EvSetRGBColor 87 
SetRGBColor 86 
response table 87 
TChooseColorDialog::TData 
class 87 
data members 
Color 87 
CustColors 87 
Error 87 
Flags 88 
TChooseFontDialog class 88 
constructor 88 
data members 
cf 89 
data 89. 
member functions 
CmFontApply 89 
DialogFunction 89 
DoExecute 89 


: TChooseFontDialog::TData 
class 89 74 


data members 
Color 90 
DC 90 
Error 90 
Flags 90 
FontType 91 
LogFont 91 _ 
PointSize 91 
SizeMax 91 
SizeMin 91 
Style 91 


TClientDC class 91 


constructor 91 


TClipboard class 92 


-data members 
DefaultProtocol 93 
IsOpen 96 
TheClipboard 97 

destructor 93 

member functions 
CloseClipboard 93 


CountClipboardFormats — 


93 
EmptyClipboard 93 
_GetClipboardData 94 
GetClipboardFormat- 
Name 94 
GetClipboardOwner 94 
GetClipboardViewer 94 
GetOpenClipboard- 
Window 95 - 
GetPriorityClipboard- 
Format 95 
IsClipboardFormat- 
Available 95 
QueryCreate 95 
QueryLink 96 


RegisterClipboardFormat 
96 | 


SetClipboardData 96 

SetClipboardViewer 96 
operators 95 

related 173 


TClipboardViewer class 97 


constructors 97 

data members 
HWndNext 97 

member functions 
DoChangeCBChain 97 
DoDestroy 97 
DoDrawClipboard 97 
EvChangeCBChain 98 
EvDestroy 98 
EvDrawClipboard 98 — 
SetupWindow 98 
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TColor class 98 
constructors 98 
data members 
Black 99 
Gray 99 
LtBlue 99 
LtCyan 99 
LtGray 99 
LtGreen 99 
LtMagenta 100 
LtRed 100 
LtYellow 100 
Value 101 
White 100 
member functions 
Blue 100 
Flags 100 
GetSysColor 100 
Green 100 
Index 101 
PalIndex 101 
PalRelative 101 
Red 101 
Reb 101 
setSysColors 101 
operators 100 
TComboBox class 102 
constructors 102 
data members 
TextLen 102 
member functions 
AddString 103 
Clear 103 
ClearList 103 
DeleteString 103 
DirectoryList 103 
FindString 103 
GetClassName 106 
GetCount 103 
GetDroppedControl- 
Rect 103 — 
GetDroppedState 103 
GetEditSel 103 
GetExtendedUI 103 
GetItemData 104 
GetItemHeight 104 
GetSelIndex 104 . 
GetString 104 — 
GetStringLen 104 
GetText 104 
GetTextLen 104 
HideList 104 
InsertString 105 
SetEditSel 105 
SetExtendedUI 105 
SetItemData 105 
SetltemHeight 105 
SetSelIndex 105 
SetSelString 105 


SetText 105 
SetupWindow 106 
ShowList 105 
Transfer 106 
TComboBoxData class 106 
constructor 106 
data members 
Selection 108 
SelIndex 108 
Strings 108 
destructor 106 
member functions 
AddString 107 
AddStringltem 107 
Clear 107 
GetlItemDatas 107 
GetSelCount 107 
GetSelection 107 
GetSelIndex 107 
GetSelString 107 
GetSelStringLength 107 
GetStrings 107 
ResetSelections 107 
Select 108 
SelectString 108 
TComboBoxData struct 
data members 
ItemDatas 108 
TCommandEnabler class 108 
constructor 111 
data members 
Handled 112 
HWndReceiver 112 
Id 111 
member functions 
Enable 111 
GetHandled 112 
IsReceiver 112 
SetCheck 112 
SetText 112 
typedefs 111 
TCommandHook typedef 
TAutoCommand 574 
TCommonDialog class 112 
constructor 113 
data members 
CDTitle 113 
member functions 
CmHelp 113 
CmOkCancel 113 
DoCreate 113 
DoExecute 113 
EvClose 114 
SetupWindow 114 
TComponentFactory member 
function 
TOleFactoryBase 315 


TComponentFactory operator 
TAutoFactory 65 
TComponentFactory 
typedef 599 
TCondFunc type 114 
TCondMemFunc typedef 114 
TControl class 117 
constructors 118 
member functions 
Compareltem 118 
DeleteItem 118 
Drawltem 118 
EvCompareltem 118 
EvDeleteltem 118 
EvDrawltem 119 
EvMeasureltem 119 
EvPaint 119 
Measureltem 119 
ODADrawEntire 119 
ODAFocus 119 
ODASelect 119 
TControlBar class 115 
constructor 115 
member functions 
PositionGadget 116 
PreProcessMsg 116 
TControlGadget class 116 
constructor 116 
data members 
Control 116 
destructor 116 
member functions 
GetDesiredSize 116 
GetInnerRect 116 
Inserted 117 
Invalidate 117 
InvalidateRect 117 
Removed 117 
SetBounds 117 
Update 117 
TCreatedDC class 120 
constructors 120 
destructor 120 
TCursor class 121 
constructors 121 
destructor 121 
member functions 
GetIconInfo 121 
operators 122 


- td transfer function 


constants 106 
TData class 
TChooseFontDialog class 89 
TData nested class 
TChooseColorDialog 87 
TFindReplaceDialog 218 
TOpenSaveDialog 344 
TPrintDialog 364 


TDC class 122 

constructors 122, 158 

data members 
Handle 158 
OrgBrush 158 
OrgFont 158 
OrgPalette 158 
OrgPen 159 
OrgTextBrush 159 
ShouldDelete 159 

destructor 122 

member functions 
AngleArc 123 
Arc 123 
BeginPath 123 
BitBlt 123 
CheckValid 159 
Chord 124 
CloseFigure 124 
DPtoLP 124 
DrawFocusRect 124 
Drawlcon 125 
DrawText 125 
Ellipse 126 
EndPath 126 
EnumFontFamilies 126 
EnumFonts 126 
EnumMetaFile 127 
EnumObijects 127 
ExcludeClipRect 127 
ExcludeUpdateRgn 128 
ExtFloodFill 128 
ExtTextOut 128 
FillPath 129 
FillRect 129 
FillRen 129 
FlattenPath 129 
FloodFill 129 
FrameRect 130 
FrameRen 130 
GetAspectRatioFilter 130 
GetAttributeHDC 159 
GetBkColor 130 
GetBkMode 130 
GetBoundsRect 130 — 
GetBrushOrg 131  ' 
GetCharABCWidths 131 
GetCharWidth 131 
GetClipBox 131 
GetClipRen 131 
GetCurrentObject 132 
GetCurrentPosition 132 
GetDCOrg 132 
GetDeviceCaps 132 
GetDIBits 132 : 
GetFontData 133 
GetGlyphOutline 133 
GetHDC 159 
GetKerningPairs 133 
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GetMapMode 133 
GetNearestColor 134 
GetOutlineTextMetrics 134 
GetPixel 135 
-GetPolyFillMode 135 
GetROP2 135 
GetStretchBltMode 135 
GetSystemPaletteEntries 
135 
GetSystemPaletteUse 135 
GetTabbedTextExtent 135 
GetTextAlign 136 
GetTextCharacterExtra 137 
GetTextColor 137 
GetTextExtent 137 
GetTextFace 137 
GetTextMetrics 138 
GetViewportExt 138 
GetViewportOrg 138 
GetWindowExt 138 
GetWindowOrg 138 
GrayString 138 
Init 159 
IntersectClipRect 139 
InvertRect 139 
InvertRen 140 
LineTo 140 
LPtoDP 140 
MaskBlt 140 
ModifyWorldTransform 
141 


MoveTo 142 

OffsetClipRen 142 

OffsetViewportOrg 142 

OffsetWindowOrg 142 

OWLFastWindowFrame 
143 

PaintRen 143 

PatBlt 143 

PathToRegion 143 

Pie 143 

PlayMetaFile 144 

PlayMetaFileRecord 144 

PleBlt 144 


RestoreObjects 148 
RestorePalette 148 
RestorePen 148 
RestoreTextBrush 148 
RoundRect 148 
SaveDC 149 : 
ScaleViewportExt 149 
ScaleWindowExt 149 
ScrollIDC 149 
SelectClipPath 150 
SelectClipRgn 150 
SelectObject 150 
SelectStockObject 150 
SetBkColor 151 
SetBkMode 151 
SetBoundsRect 151 
SetBrushOrg 151 
SetDIBits 151 
SetDIBitsToDevice 152 
SetMapMode 152 
SetMapperFlags 152 
SetMiterLimit 152 
SetPixel 153 
SetPolyFillMode 153 
SetROP2 153 
SetStretchBltMode 153 
SetSystemPaletteUse 154 
SetTextAlign 154 
SetTextCharacterExtra 154 
SetTextColor 154 
SetTextJustification 154 
SetViewportExt 154 
SetViewportOrg 155 
SetWindowExt 155 
SetWindowOrg 155 
SetWorldTransform 155 
StretchDIBits 155,156 ~ 
StrokeAndFillPath 156 
StrokePath 156 
TabbedTextOut 156 
TextOut 157 

TextRect 157 
UpdateColors 157 
WidenPath 157 


SetClientWindow 161 
SetupWindow 161 — 
typedefs 160 


TDecoratedMDIFrame class 162 


constructor 162 
member functions 
DefWindowProc 162 


TDesktopDC class 163 


constructor 163 


tdGetData constant 106, 256, 


270, 394, 411 
tdGetData enum 384, 438 
TDialog class 163 


constructor 164 

data members 
Attr 164 
IsModal 164 

destructor 164 

member functions 
CloseWindow 164 
CmCancel 164 
CmOk 165 
Create 165 
Destroy 165 
DialogFunction 165 
DoCreate 165 
DoExecute 165 
EvClose 165 
EvCtlColor 165 
EvInitDialog 166 
EvPaint 166 
EvSetFont 166 
Execute 166 
GetClassName 167 
GetDefaultId 166 
GetWindowClass 167 
GPerformDlgInit 167 
PreProcessMsg 167 
SetCaption 167 
SetDefaultId 167 
SetupWindow 168 

member functions, obsolete 
GetltemHandle 166 


PolyBezier 145 
PolyBezierTo 145 


SendDlgItemMsg 167 
TDialog::TDialogAttr struct 168 


operators 139 
TCreateDC vs. 122 


PolyDraw 145 TDecoratedFrame class 159 data members 
Polygon 146 constructor 160 Name 168 
Polyline 146 data members Param 168 


PolylineTo 146 
ee ak 146 


MenultemlId 161 
TrackMenuSelection 161 


TDib class 169 
constructors 169 


PolyPolyline 147 member functions data members 
PtVisible 147 EvCommand 161 Bits 174 
RealizePalette 147 EvCommandEnable 161 H 174 
Rectangle 147 EvEnterldle 161 Info 174 
RectVisible 147 EvMenuSelect 161 IsCore 175 
ResetDC 147 | EvSize 161 IsResHandle 175 
RestoreBrush 148 Insert 160 Mode 175 


RestoreDC 148 
RestoreFont 148 
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PreProcessMsg 160 


NumcClrs 175 
W 175 


destructor 170 
member functions 
ChangeModeToPal 170 
ChangeModeToRGB 171 


FindColor 171 
FindIndex 171 
GetBits 171 
GetColor 171 
GetColors 171 
GetIndex 171 
GetIndices 171 
GetInfo 172 
GetInfoHeader 172 
Height 172 
InfoFromHandle 175 
IsOk 172 

IsPM 172 
LoadFile 175 


EvPreProcessMenu 179 


EvWakeUp 179 
FindDocument 180 
FlushDoc 180 
GetApplication 180 
GetCurrentDoc 180 
GetNextTemplate 180 
InitDoc 180 
IsFlagSet 180 
MatchTemplate 180 
PostDocError 181 
PostEvent 181 
RefTfemplate 181 
SelectAnySave 181 
SelectDocPath 181 
SelectDocType 182 
SelectSave 181 
SelectViewlType 182 
UnRefTemplate 181 


TDocTemplate class 679 


GetViewName 685 
IsMyKindOfDoc 684 
IsMyKindOfView 685 


TDocument class 182 
constructor 184 
data members 

ChildDoc 183 
DirtyFlag 189 
Embedded 189 
Tag 183 
destructor 184 
member functions 


AttachStream 189 


CanClose 184 
Close 184 
Commit 184 


DetachStream 189 
FindProperty 185 


GetDocPath 185 


GetOpenMode 185 


constructor 683 
destructor 683 
member functions 


LoadResource 175 
MapColor 172 
MapIndex 172 


GetParentDoc 185 
GetProperty 185 
GetTemplate 185 


MapUIColors 173 
numColors 173 
numScans 173 
Read 176 
SetColor 173 
SetIndex 173 
Size 173 
StartScan 174 
ToClipboard 174 
Usage 174 
Width 174 
WriteFile 174 


operators 170, 172, 173, 174 
typedefs 169 
TDibDC class 176 
constructor 176 
TDocManager class 176 
constructor 177 
data members 


DocList 177 


destructor 177 
member functions 


AttachTemplate 178 
CmFileClose 178 
CmFileNew 178 
CmFileOpen 178 
CmFileRevert 178 
CmFileSave 178 
CmFileSaveAs 178 


ClearFlag 679 

Clone 680 
ConstructDoc 680 
ConstructView 680 
CreateDoc 680 
CreateView 680 
GetDefaultExt 680 
GetDescription 680 
GetDirectory 680 
GetDocManager 681 
GetFileFilter 681 
GetFlags 681 
GetModule 681 
GetNextTemplate 681 
GetRegList 681 
InitDoc 681 
InitView 681 
IsFlagSet 681 
IsMyKindOfDoc 682 
IsMyKindOfView 682 
IsStatic 682 
IsVisible 682 
SelectSave 682 
SetDefaultExt 682 
SetDirectory 682 
SetDocManager 682 
SetFileFilter 682 
SetFlag 682 
SetModule 683 


GetTitle 185 
HasFocus 186 
InitDoc 186 
InStream 186 
IsDirty 186, 188 
IsOpen 186 
NextStream 186 
NextView 186 
NotifyViews 186 
Open 187 
OutStream. 187 
PostError 187 


PropertyCount 187 
PropertyFlags 187 
PropertyName 187 


QueryViews 188 
Revert 188 


RootDocument 188 
SetDocmanager 188 


SetDocPath 188 


SetOpenMode 188 


SetProperty 188 
SetTemplate 189 
SetTitle 189 


templates, creating 34 


typedefs 184 


TDocument::List class 189 


constructor 189 
destructor 189 


CmViewCreate 178 templates, creating 34 member functions 
CreateAnyDoc 178 TDocTemplateTD,V class 683 Destroy 190 
CreateAnyView 179 constructor 684 Insert 190 
CreateDoc 179 member functions Next 190 
CreateView 179 Clone 684 _ Remove 190 


CreateDoc 684 


DeleteTemplate 179 
CreateView 684 


TDropInfo class 685 
EvCanClose 179 


constructor 685 
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member functions | 
DragFinish 685 
DragQueryFile 685 


- DragQueryFileCount 685 
DragQueryFileNameLen 


686 
DragQueryPoint 686 
operator 686 


tdSetData constant 106, 256, 


270, 394, 411 


tdSetData enum. 384, 438 
tdSizeData constant 106, 256, 


270, 394, 411 


tdSizeData enum 384, 438 
TEdgeConstraint struct 190 


member functions 
Above 190 
Absolute 190 
Below 191 
LeftOf 191 
PercentOf 191 
RightOf 191 
SameAs 191 
Set 191 


TEdgeOrSizeConstraint 


struct 191 

member functions 
Absolute 192 
PercentOf 192 
SameAs 192 


TEdit class 192 


constructors 193 

data members 
Validator 198 

member functions 
CanClose 198 
CanUndo 193 
Clear 193. 
ClearModify 193 
CmCharsEnable 199 
CmEditClear 199 
CmEditCopy 199 
CmEditCut 199 
CmEditDelete 199 
CmEditPaste 199 
CmEditUndo 199 
CmModEnable 199 
CmPasteEnable 199 
CmSelectEnable 200 
Copy 193 
Cut 194 

- DeleteLine 194 

DeleteSelection 194 
DeleteSubText 194 


EmptyUndoBuffer 194 _ 


ENErrSpace 200 
EvChar 200 
EvGetDlgCode 200 


EvKeyDown. 200 
EvKillFocus: 200 
FormatLines 194 
GetClassName 200 


GetFirstVisibleLine 194 


GetHandle 194 
GetLine 194 
GetLineFromPos 195 
GetLinelndex 195 
GetLineLength 195 
GetNumLines 195 


GetPasswordChar 195 _ 


GetRect 195 
GetSelection 195 
GetSubText 196 


GetWordBreakProc 196 


Insert 196 
IsModified 196 
IsValid 196 
LockBuffer 196 
Paste 196 
Scroll 196 
Search 197 
SetHandle 197 


SetPasswordChar 197 


SetReadOnly 197 
SetRect 197 
SetRectNP 197 
SetSelection 197 
SetTabStops 197 
SetupWindow 201 
SetValidator 197 


SetWordBreakProc 198 


Transfer 198 
Undo 198 
UnlockBuffer 198 
ValidatorError 198 


TEditFile class 201 


constructor 201 
data members 
FileData 202 
FileName 202 
destructor 201 
member functions 
CanClear 202 
CanClose 202 | 
CmFileNew 202 
CmFileOpen. 202 
CmFileSave 202 
CmFileSaveAs 202 
NewFile 203 
Open 203 
Read 203 | 
ReplaceWith 203 
Save 203 
SaveAs 203 
SetFileName 203 
SetupWindow 204 
Write 203 
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TEditSearch class 204 
constructor 204 
data members 
SearchCmd 204 
SearchData 204 
SearchDialog 204 
member functions 
CmEditFind 205 
CmEditFindNext 205 
CmEditReplace 205 
DoSearch 205 
EvFindMsg 205 
SetupWindow 205 
TEditView class 206 
constructor 206 © 
data members 
Origin 207 
destructor 206 
member functions 
CanClose 206 
Create 206 
EvNCDestroy 207 
GetViewName 206 
~GetWindow 207 
LoadData 207 
~ PerformCreate 207 
SetDocTitle 207 
StaticName 207 
VnCommit 207 
VnDocClosed 208 - 
VnisDirty 208 
VnIsWindow 208 
VnkRevert 208 
TEllipse enum 384 
template factory classes 36 
templates 
creating 32, 34 
documents 189 
TEqualOperator typedef 208 
TermInstance member function 
TApplication 63 


_ TError typedef 


TxXAuto 661 
TXObjComp 662 
TErrorMsgHook typedef 
TAutoCommand 575 > 
test function 466 
Test member function 
TAutolterator 583 
TestFlag member function 
TAutoCommand 577 
TEventHandler class 209 
member functions 
Dispatch 209 
— Find 209 
SearchEntries 209 


TEventHandler::TEventinfo 
class 209 
constructor 209 
data members 
Entry 210 
Id 210 
Msg 210 
Object 210 
enums 210 
TEventInfo nested class 209-210 
TEventStatus enum 210 
text 
buffers 256 
changing 410 
Clipboard and. 193 
copying 199 
deleting 194 
editing 192 
finding 216 
inserting 
current position 196 
length 410 
modifying 196 
pasting 196 
replacing 216, 387 
retrieving user input 255 
searching for 197, 204 
selecting 195, 197 
static controls 411 
interface element 410 
status bar 414 
Text data member 
TTextGadget 423 
text gadgets 422 
textgadg.h 23 
TextLen data member 
TComboBox 102 
TStatic 410 
TTextGadget 423 
TEXTMETRIC struct 734 
TextOut member function 
TDC 157 
TextRect member function 
TDC 157 
TFileDocProp enum 211 
TFileDocument class 210 
closing files 211 
constructor 211 
data members 
FHdl 213 
destructor 211 
member functions 
Close 211 
CloseThisFile 213 
Commit 211 
FindProperty 212 _ 
GetProperty 212 


InStream 212 
IsOpen 212 
ne 212 
OpenThisFile 213 
OutStream 212 
PropertyFlags 212 
PropertyName 213 
Revert 213 
SetProperty 213 
typedefs 211 
TFileOpenDialog class 213 
constructor 214 
member functions 
DoExecute 214 
TFileSaveDialog class 214 
constructor 214 
member functions 
DoExecute 214 
TFilterValidator class 215 
constructor 215 
data members 
ValidChars 215 
member functions 
Error 215 
IsValid 215 
IsValidInput 215 
TFindDialog class 216 
constructor 216 
member functions 
DoCreate 216 
TFindReplaceDialog class 216 
constructor 216 
data members 
Data 217 
fr 217 
member functions 
CmCancel 217 
CmFindNext 217 
CmReplace 217 
CmReplaceAll 217 
DialogFunction 217 
DoCreate 217 
EvNCDestroy 217 
Init 218 
TFindReplaceDialog::TData 
class 218 
constructor 218 
data members 
BuffSize 218 
Error 218 
FindWhat 219 
Flags 219 
ReplaceWith 219 
destructor 218 
errors 218 
TFloatingFrame class 219, 425 
constructor 220 
member functions 


DoNCHitTest 220 
SetMargins 220 


TFont class 221 


constructors 221 

member functions 
GetObject 222 

operators 222 


TFrameWindow class 222 


constructors 222, 226 

data members 
ClientWnd 225 
DoctTitleIndex 225 
HWndRestoreFocus 225 
KeyboardHandling 223 
MergeModule 226 

destructor 223 

member functions 
AssignMenu 223 
EnableKBHandler 223 
EvCommand 226 
EvCommandEnable 226 
EvEraseBkend_ 226 
EvInitMenuPopup 226 
EvPaint 226 
EvParentNotify 227 
EvQueryDraglcon 227 
EvSetFocus 227 
EvSize 227 
GetClientWindow 223 
GetCommandTarget 223 
GetMenuDescr 224 
HoldFocusHwnd 224 
IdleAction 224 
Init 227 
MergeMenu 224 
PreProcessMsg 224 
RestoreMenu 224 
SetClientWindow 224 
SetDocTitle 225 
SetIcon 225 
SetMenu 225 
SetMenuDescr 225 
SetupWindow 227 


TGadget class 228 


constructor 229 

data members 
Borders 232 
BorderStyle 232 
Bounds 232 
Clip 229 
Id 232 
Margins 232 
ShrinkWrapHeight 232 
ShrinkWrapWidth 233 
TrackMouse 233 
WideAsPossible 229 
Window 233 

destructor 229 

enums 229 
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member functions 
CommandEnable 230 
GetBorders 230 
GetBorderStyle 230 
GetBounds 230 
GetDesiredSize 230 
GetEnabled 231 
Getld 231 
GetInnerRect 233 
GetMargins 231 
GetOuterSizes 231 
Inserted 233 
Invalidate 233 
InvalidateRect 233 
LButtonDown 233 
LButtonUp 233 
MouseEnter 233 
MouseLeave 234 
MouseMove 234 
NextGadget 231 
Paint 234 
PaintBorder 234 
PtIn 234 
Removed 234 
SetBorders 231 
SetBorderStyle 231 
SetBounds 231 
SetEnabled 231 
SetMargins 231 
SetShrinkWrap 232 
SetSize 232 
syscolorChange 232 
Update 234 

structures 229 
TBorders 229 
TMargins 230 


TGadgetWindow class 236 


constructor 236 

data members 
AtMouse 239 
BkgndBrush 239 
Capture 239 
DirtyLayout 240 
Font 240 | 
Gadgets 240 
HintMode 240 
Margins 240 
NumGadgets 240 


ShrinkWrapHeight 240 


ShrinkWrapWidth 240 
WideAsPossible 240 

destructor 236 

member functions 
Create 241 

~ EvLButtonDown 241 — 

EvLButtonUp 241 
EvMouseMove 241 
EvSize 241 


EvSyscolorChange 241 


FirstGadget 237 
GadgetChangedSize 237 
GadgetFromPoint 237 
GadgetReleaseCapture 237 
GadgetSetCapture 237 
GetDesiredSize 241 
GetDirection 237, 239 
GetFont 237 
GetFontHeight 237, 240 
GetHintMode 237 
GetInnerRect 241 
GetMargins 242 
IdleAction 238 
Insert 238 _ 
LayoutSession 238 
LayoutUnitsToPixels 242 
NextGadget 238 
Paint 242 
PaintGadgets 242 
PositionGadget 242 
Remove 238 
SetDirection 238 
SetHintCommand 239 
SetHintMode 239 
SetMargins 239 
setShrinkWrap 239 
TGadgetWithld 237 
TileGadgets 242 
typedefs 236 
TGadgetWindowFont class 234 
constructor 235 
TGadgetWithId member 
function 
TGadgetWindow 237 
TGauge class 243 
constructor 243 
data members 
BarColor 244 
IsHorizontal 244 
LedSpacing 244 
LedThick 244 
Margin 244. 
Max 244 
Min 244 
Value 244 
member functions 
EvEraseBkgend 245 
GetRange 243 
GetValue 243 
Paint 245 : 
PaintBorder 245 
SetColor 243 
SetLed 243 
SetRange 244 
SetValue 244 
TGdiObject class 245 
constructors 248 
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data members 
Handle 248 
ShouldDelete 248 
destructor 246 
macros 248-249 
member functions 
CheckValid 248 
GetObject 246 
~RefAdd 247 
RefCount. 247 
RefDec 247 
RefFind 247 
Reflnc 247 
RefRemove 247 
operators 248 
typedefs 246 | 
TGdiObject::TXGdi class 250 
constructor 250 
member functions 
Clone 250 
Msg 250 
Throw 250 
TGroup enum 296 
TGroupBox class 250 
constructors 251 
data members 
NotifyParent 251 
member functions 
GetClassName 251 
SelectionChanged 252 
THatch8x8Brush class 252, 432 
constructor 253 — 
data members 
Hatch11F1[8] 252 
Hatch13B1[8] 252 
Hatch13F1[8] 253 
Hatch22B1[8] 253 
Hatch22F1[8] 253 
member functions 
Reconstruct 253 
TheClipboard data member 
TClipboard 97 
THintMode enum 236 
this parameter 50 — 
ThisOpen data member 
TStorageDocument 420 
ThisUnknown member function 
TUnknown 660 
Throw member function | 
TGdiObject::TXGdi 250 
TXBase 700 
TXCompatibility 500, 501 
TXInvalidMainWindow 63 
TXInvalidModule 310 
TXOutOfMemory 502 
TXOwl1 504 
TXWindow 500 


throwing exception objects 
TXBase class 700 
TXCompatibility class 500 
TXGdi class 250 
TXInvalidMainWindow 
class 63 
TXInvalidModule class 310 
TXMenu class 501 
TXOutOfMemory class 502 
TXOw1l class 504 
TXWindow class 500 
THSlider class 405 
constructor 406 
member functions 
HitTest 406 
NotifyParent 406 
PaintRuler 406 
PaintSlot 406 
PaintToPos 406 
PosToPoint 406 
thumb, scroll bars 391, 392 
moving 392, 393 
returning position 392, 394 
thumbnail aspect 537, 608 
ThumbRect data member 
TSlider 405 
ThumbResId data member 
TSlider 405 
TIC class 253 
constructor 254 
TicGap data member 
TSlider 405 
tick positions | 
sliders and 399, 400 
TIcon class 254 
constructors 254 
destructor 254 
member functions 
GetIconInfo 255 
operator 255 
TileChildren member function 
TMD!IClient 283 
TileGadgets data member 
TToolBox 432 
TileGadgets member function 
TGadgetWindow 242 
tiling 283 
direction 431 
timer event 476, 485 
TInputDialog class 255 
constructor 255 
control IDs 40 
data members 
buffer 255 
BufferSize 255 
prompt 255 


member functions 
SetupWindow 256 
TransferData 256 
TInStream class 256 
constructor 256 
tinycapt.h 23 
Title data member 
TWindow 456 
titles 
documents 189 
updating 474 
TLangld typedef 686 
TLayoutConstraint struct 256 
data members 
MyEdge 257 
OtherEdge 257 
Relationship 257 
RelWin 258 
Units 258 


TWidthHeight enum and 454 


unions 258 

TLayoutMetrics class 258 
constructor 259 
data members 

Height 259 
Width 259 
X 259 
Y 259 

TLayoutWindow class 261 
constructor 263 
data members 

ClientSize 264 
destructor 263 
member functions 
EvSize 264 
GetChildLayoutMetrics 
263 
Layout 264 
RemoveChildLayout- 
Metrics 264 
SetChildLayoutMetrics 
264. 

TListBox class 264 
constructors 265 
member functions 

AddString 265 
ClearList 265 
DeleteString 265 
DirectoryList 265 
FindExactString 266 
FindString 266 
GetCaretIndex 266 
GetClassName 270 
GetCount 266 
GetHorizontalExtent 266 
GetlItemData 266 
GetltemHeight 266 
GetltemRect 266 


GetSel 267 
GetSelCount 267 
GetSelIndex 267 
GetSellndexes 267 
GetSelString 267 
GetSelStrings 267 
GetString 267 
GetStringLen 267 
GetTopIndex 268 
InsertString 268 
SetCaretIndex 268 
SetColumnWidth 268 
SetHorizontalExtent 268 
SetltemData 268 
SetIltemHeight 268 
SetitemRect 268 
SetSel 268. 
SetSelIndex 269 
SetSelIndexes 269 
SetSelltemRange 269 
SetSelString 269 
SetSelStrings 269 
SetTabStops 269 
SetTopIndex 269 
Transfer 270 


TListBoxData struct 270 


constructor 271 

data members 
ItemDatas 270 
SelCount 270 
SelIndices 270 
SelStrings 270 
Strings 270 

destructor 271 

member functions 
AddString 271 
AddStringlItem 271 
Clear 271 
GetltemDatas 271 
GetSelIndices 271 
GetSelString 271 
GetSelStringLength 271 
GetString 272 
ResetSelections 272 
Select 272 
SelectString 272 


TListView class 272 


constructor 272 
data members 
DirtyFlag 272 
MaxWidth 273 
Origin 274 
destructor 272 
member functions 
CanClose 273 | 
CmEditAdd 274 
CmEditClear 274 
CmEditCopy 274 
CmEditCut 274 
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CmEditDelete 274 
CmEditItem 274 
CmEditPaste 274 
CmEditUndo 274 
CmSelChange 275. 
Create 273 
EvGetDlgCode 275 
GetViewName 273 
GetWindow 273 
LoadData 275 
SetDocTitle 273 
SetExtent 275 
StaticName 273 
VnCommit 275 
VnDocClosed 275 
VnisDirty 275 
VnIsWindow 275 
VnRevert 276 
TLocaleld typedef 599 
TLocaleString struct 276 
member functions 
Compare 277 
GetSystemLangld 277 
_ GetUserLangld 277 
IsNativelangId 277 
Translate 278 
operators 277,278 
TLocation enum 160 
TLookupValidator class 278 
constructor 278 
member functions 
IsValid 278 
Lookup 279 
TMargins struct 
TGadget class 230 
TMDI frame 
keyboard navigation 285 
TMD!IChild class 279 
constructors 279 
destructor 279 
member functions 
DefWindowProc 280 
Destroy 280 
EnableWindow 280 
EvMDIActivate 280 
EvNCActivate 280 
PerformCreate 280 
PreProcessMsg 280 
ShowWindow 280 
TMDiIClient class 281 
constructor 281 
- data members 
ClientAttr 281 
destructor 281 
member functions 
Arrangelcons 281 
CascadeChildren 282 
CloseChildren 282 


-~CMArrangelcons 283 
CmCascadeChildren 283 


~ CmChildActionEnable 283 


-CmCloseChildren 283 
CmCreateChild 283 
CmTileChildren 283 


CmTileChildrenHoriz 283 


Create 282 
CreateChild 282 
EvMD!ICreate 284. 
EvMbD Destroy 284 


GetActiveMDIChild 282 | 


GetClassName 284. 
InitChild 282 
PreProcessMsg 282 
TileChildren 283 
TMD IFrame class 284 
constructors 285 
member functions 
DefWindowProc 286 
FindChildMenu 285 
GetClientWindow 286 
GetCommandTarget 286 
PerformCreate 286 
SetMenu 286 
TMeasurementUnits enum 286 
TMemoryDC class 287 
constructors 287 | 
data member 
OrgBitmap 288 
member functions 
RestoreBitmap 287 
RestoreObjects 287 
SelectObject 287 
TMenu class 288 
constructors 288 
data members 
DeepCopy 293 
Handle 292 
ShouldDelete 292 
destructor 288 
member functions 
sh aes 289 
ckMenultem 289 © 
CheckValid 289 
DeleteMenu 289 
Drawltem 289 
EnableMenultem 289 
GetHandle 289 | 
GetMenuCheckMark- 
Dimensions 290 
GetMenultemCount 290 
GetMenultemID 290 
GetMenuState 290 
GetMenuString 290 
GetSubMenu 291 
InsertMenu 291 
IsOK 291 
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Measureltem 291 
ModifyMenu 291 
RemoveMenu 292 
SetMenultemBitmaps 292 
operators 291, 292 
resource [Ds 495 
~TXMenu class 501 
TMenuDesc class 
member functions 
ClearContainerGroup- 
Count 297 
ClearServerGroup- 
Count 297) 
ExtractGroups 298 
GetGroupCount 297 
GetHandle 296 
GetlId 297 
GetModule 297 
Merge 297 
SetModule 297 
typedefs 296 
TMenuDescr class 293 
constructors 295 
data members 
GroupCount 298 
Id 297 
Module 298 
typedefs 296 
TMenultemEnabler class 298 
constructor 298 
data members 
HMenu 298 
Position 298 
member functions 
Enable 299 
GetMenu 299 
GetPosition 299 
SetCheck 299 
SetText 299 
T'MessageBar class 299 
constructor 299 
data members | 
Highlightline 300 
HintText 300 | 
member functions 
GetDesiredSize 300 
GetInnerRect 300 
PaintGadgets 300 
SetHintText 300 
— SetText 300 
TMetaFileDC 
constructor 301 
destructor 301 
TMetaFileDC class 300 
member functions 
Close 301 
TMetaFilePict class 301 
constructors 301 


data members 
Extent 303 
Mm 303 

destructor 302 

member functions 
CalcPlaySize 302 
GetMetaFileBits 302 
GetMetaFileBitsEx 302 
Height 302 
MappingMode 302 
PlayOnto 302 
SetMappingMode 303 
SetSize 303 
Size 303 
ToClipboard 303 
Width 303 

operators 302 


TModule class 303 


constructors 303 

data members 
HInstance 310 
IpCmdLine 304 
Module 304 
Status 304 

destructor 304 

member functions 
AccessResource 304 
AllocResource 305 
CopyCursor 305 
Copylcon 305 
Error 305 
ExecDialog 305 
FindResource 305 
GetClassInfo 306 
GetClientHandle 306 
Getinstance 306 
GetInstanceData 306 
GetModuleFileName 306, 

310 

GetModuleUsage 307 
GetName 307 
GetParentObject 307 
GetProcAddress 307 
InitModule 307 
IsLoaded 307 
LoadAccelerators 307 
LoadBitmap 307 
LoadCursor 308 
LoadIcon 308 
LoadMenu 308 
LoadResource 308 
LoadString 308 
LowMemory 308 
MakeWindow 308 
RestoreMemory 309 
SetInstance 309 
SetName 309 
SetResourceHandler 309 


SizeOfResource 309 
ValidWindow 309 
operators 309 
TModule 


class::TXInvalidModule 310 


TObjectDescriptor member 
function 
TAutoObjectDelete 587 
TObjectDescriptor() operator 
TAutoObject 585 
TOcApp class 600 
constructor 606 
destructor 606 
member functions 


AddUserFormatName 601 


Browse 601 
BrowseClipboard 602 
CanClose 602 

Clip 602 

Convert 602 

Drag 602 
EnableEditMenu 603 
EvActivate 603 
EvResize 603 
EvSetFocus 603 


ForwardEvent 606, 607 


GetName 603 
GetNameList 603 
GetRegistrar 604 
IsOptionSet 604 
Paste 604 
RegisterClass 604 
RegisterClasses 604 
ReleaseObject 605 
SetOption 605 
SetupWindow 605 
TranslateAccel 605 
UnregisterClass 605 
UnregisterClasses 606 
typedefs 600 
TOcAppMode enum. 607 
TOcAspect enum. 608 
TOcDialogHelp enum 608 
TOcDocument class 609 
constructors 610 
member functions 
Close 610 
GetActiveView 610 
GetName 610 
GetParts 611 
GetStorage 611 
LoadParts 611 
RenameParts 611 
SaveParts 611 
SaveToFile 612 
SetActiveView 612 
SetName 612 
SetStorage 612 


TOcDragDrop structure 613 
data members 
InitInfo 613 
Pos 613 
Where 613 
TOcDropAction enum 613 
TOcFormatList class 614 
constructor 614 
destructor 614 
member functions 
Add 614 
Clear 615 
Count 615 
Detach 615 
Find 615 
IsEmpty 615 
TOcFormatListlter class 615 
constructor 616 | 
member functions 
Current 616 
Restart 616 
operator 616 
TOcFormatName class 616 
constructors 617 
destructors 617 
member functions 
GetId 617 
GetName 617 
GetResultName 617 
operator 617 
TOcInitHow enum 618 
TOcInitInfo class 618 
constructors 620 
data members 
ClId 619 
Container 618, 620 
Data 619 
Handle 620 
HIcon 619 
How 619 
Path 619 
Storage 619 
Where 619 
member functions | 
ReleaseDataObject 620 
TOcInitWhere enum 621 
TOcInvalidate enum 621 
ToClipboard member function 
TBitmap 67 
TDib 174 
TMetaFilePict 303 
TPalette 350 
TOcMenuDescr structure 621 
data members 
HMenu 622 
Width 622 
TOcMenuEnable enum 
TOcApp 600 
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TOcModule class 622 
constructor 623 
data members | 

OcApp 624 
OcInit 623 
OleMalloc 624 
destructor 623 
member functions 
GetRegistrar 623 
IsOptionSet 623 

TOcNameList class 624 
constructors 624 
destructors 624 
member functions 

Add 625 
Clear 625 
Count 625 
Detach 625 
Find 625 © 
IsEmpty 625 
operators 625 
TOcPart class 626 _ 

| ‘constructors 626 

destructors 631 

member functions 
Activate 626 
Close 627 
Delete 627 
Detach 627 
DoVerb 627 
Draw 627 
-EnumVerbs 627 
GetName 628 
GetNameLen 628 
GetPos 628 
GetRect 628 


GetServerName 628 


GetSize 628 
IsActive 628 
IsSelected 629 
IsVisible 629 
Load 629 
Open. 629 
Rename 629 
Save 630 
Select 630 
SetActive 630 
SetHost 630 
SetPos 631 
SetSize 631 
SetVisible 631 
Show 631 
UpdateRect 631 
operators 626 


TOcPartCollection class 631 


constructor 632 
destructor 632 


member functions 

Add 632 
Clear 632 ~. 
Count 632 
Detach 632 
Find 632 
IsEmpty 632 
Locate 633 
SelectAll 633 


TOcPartCollectionIter class 633 


constructor 633 
‘member functions 
Current 634 
Restart 634 
operators 634 
TOcPartName enum 634 
TOcRegistrar class 634 
member functions 
BOleComponentCreate 
635 
CanUnload 636 — 
CreateOcApp 636 


GetAppDescriptor 636 


GetFactory 636 
LoadBOle 637 
TOcRemView class 637 
constructors 637 
member functions 
Copy 638 
EvClose 638 
GetContainerTitle 638 
GetInitialRect 638 
Invalidate 638 
IsOpenEditing 639 
Load 639 
Rename 639 
Save 639 
TOcSaveLoad structure 639 
data members 
Release 640 
Storagel 640 . 
TOcScaleFactor class 640 
member functions 
GetScale 642 
GetScaleFactor 642 
IsZoomed 642 
PartSize 641 
SetScale 642 
SiteSize 641 
operators 641 


-TOcScrollDir enum 642 


TOcToolBarInfo structure 642 
data members 
HBottomTB 643 
HFrame 643 
HLeftTB 643 
HRightTB 643 
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HTopTB 643 
Show 643 
TOcVerb class 644 . 
constructors 644 
data members 
CanDirty 644 _ 
TypeName 644 
VerbIndex 645 
VerbName 645 
TOcView class 645 
constructors 645 
data members 
Extent 650 
FormatList 650 
Link 650 
OcApp 650 
OcDocument 650 
Origin 651 
Win 651 
WintTitle 651 
member functions 
ActivatePart 646 
BrowseClipboard 646 
BrowseLinks 646 
Copy 646 
EvActivate 646 
EvClose 647 
EvResize 647 
EvSetFocus 647 
ForwardEvent 649 
GetActivePart 647, 650 
GetOcDocument 647 
GetOrigin 647 
GetWindowRect 647 
InvalidatePart 648 
Paste 648 
RegisterClipFormats 648 
ReleaseObject 648 
Rename 648 
ScrollWindow 648 
SetLink 649 
SetupWindow 649 
TOcViewPaint structure 651 
data members 
Aspect 651 
Clip 651 
DC 652 
Paint 652 
Pos 652 
Toggle member function 
TCheckBox 84 
ToggleModelIndicator member 
function 
TStatusBar 415 
TOleAllocator class 652 
constructor 652 
data members 
Mem 653 


destructor 653 
member functions 
Alloc 653 
Free 653 
TOleClientDC class 310 
constructor 311 
TOleDocument class 311 
constructor 311 
destructor 311 
member functions 
CanClose 312 
Commit 312 
GetNewStorage 312 
GetOcApp 312 
GetOcDoc 312 
InitDoc 313 
Open 313 
PathChanged 313 
PreOpen 313 
Read 313 
ReleaseDoc 313 
SetOcDoc 314 
SetStorage 314 
Write 314 


TOleFactoryBase<> class 314 


member functions 
Create 315 
CreateApp 315 
CreateObject 316 
DestroyApp 316 


TComponentFactory 315 


TOleFrame class 316 
constructor 317 
data members 


DestroyStashedPopups 


320 
HoldMenu 320 
StashCount 320 

destructor 317 
member functions © 


AddUserFormatName 317 
CanClose 318 
CleanupWindow 318 
Destroy 318 
DestroyStashedPopups 
318 
EvActivateApp 318 
EvOcApp 320 
Beene 
318 
EvOcAppBorderSpaceSet 
318 
EvOcAppDialogHelp 319 
EvOcAppFrameRect 319 
EvOcAppInsMenus 319 
EvOcAppProcessMsg 319 
EvOcAppRestoreUI 319 © 
EvOcAppShutdown. 319 
EvOcAppStatusText 319 


EvOcEvent 319 
EvSize 320 
EvTimer 320 
GetOcApp 317 
GetRemViewBucket 317 
are 317 
Hip Window 320 
Stas ContainerPopups 320 


TOleMDIFrame class 321 
constructor 322 
destructor 322 
member functions 


DefWindowProc 322 
EvActivateApp 322 
EvOcAppInsMenus 322 


TOleView class 323 
constructor 323 
destructor 323 
member functions 


CanClose 324 
CreateOcView 324 
EvOcView AttachWindow 
325 
EvOcViewClose 325 
EvOcViewlInsMenus 325 
EvOcViewLoadPart 325 
EvOcViewOpenDoc 325 
EvOcViewPartInvalid 325 
EvOcViewSavePart 325 
GetViewName 324 
GetWindow 324 
SetDocTitle 324 
StaticName 324 
VniInvalidateRect 326 


-TOleWindow class 326 
constructor 327 
data members 


ContainerName 329 
DragDC 329 
DragHit 329 
DragPart 329 
DragPt 329 
DragRect 329 
DragStart 329 
Embedded 329 
OcApp 329 
OcDoc 330 
OcView 330 

Pos 330 

Scale 330 
ShowObjects 330 


destructor 327 
member functions 


CanClose 330 
CeEditConvert 330 
CeEditCopy 330 
CeEditCut 331 
CeEditDelete 331 
CeEditInsertObject 331 


CeEditLinks 331 
CeEditObject 331 
CeEditPaste 331 
CeEditPasteLink 331 
CeEditPasteSpecial 331 
CeEditVerbs 331 
CeFileClose 332 
CleanupWindow 332 
CmEditConvert 332 
CmEditCopy 332 
CmEditCut 332 
CmEditDelete 332 
CmEditInsertObject 332 
CmEditLinks 332 
CmEditPaste 332 
CmEditPasteLink 332 
CmEditPasteSpecial 333 
CmFileClose 333 
CreateOcView 333 
CreateVerbPopup 333 
Deactivate 328 
EvCommand 333 
EvCommandEnable 333 
EvDoVerb 334 
EvLButtonDbIClk 334 
EvLButtonDown 334 
EvMDtIActivate 334 
EvMouseMove 334 
EvOcEvent 334 
EvOcGetPalette 336 
EvOcInsMenus 336 
EvOcPartInvalid 335 
EvOcView AttachWindow 
335 
EvOcViewBorderSpace- 
Req 335 
EvOcViewBorderSpaceSet 
335 


EvOcViewClipData 335 
EvOcViewClose 335 
EvOcViewDrag 335 
EvOcViewDrop 336 
EvOcViewGetScale 336 
EvOcViewGetSiteRect 336 
EvOcViewLoadPart 336 
EvOcViewOpenDoc 336 
EvOcViewPaint 337 
EvOcViewPartInvalid 337 
EvOcViewPartSize 337 
EvOcViewSavePart 337 
EvOcViewScroll 337 
EvOcViewSetScale 337 
EvOcViewSetSiteRect 338 
EvOcViewShowTools 338 
EvOcViewTitle 338 
EvRButtonDown 338 
EvRButtonUp 334 
EvSetCursor 338 
EvSetFocus 339 

EvSize 339 
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GetInsertPosition 339 
GetLogPerUnit 339 
GetOcApp 328 
GetOcDoc 328 
GetOcRemView 328 
GetOcView 328 : 
HasActivePart 328 
~ Init 339 
InvalidatePart 339 
Paint 339 | 
PaintMetafile 328 
PaintParts 339 
Select 340 
SelectEmbedded 340 
SetScale 340 
SetSelection 340 
SetupDC 340 . 
SetupWindow 340 
VuniInvalidateRect 340 
toolbars 159 
toolbox gadgets 430 
toolbox.h 23 
top window 472 
ToPage data member 
TPrintDialog::TData 366 
TOpenSaveDialog class 342 
constructors 342, 343 
data members 
Data 343 
ofn 343 
ShareViMseld 343 
member functions - 
CmLbSelChanged 343 
CmOk 343 | 
DialogFunction 343 
DoExecute 344 
GetFileTitle 342 
GetFileTitleLen 342 
Init 344 
ShareViolation 344 
TOpenSaveDialog::TData 
struct 344 
constructor 344 
data members 
CustomFilter 345 
DefExt 345 
Error 345 
FileName 345 
Filter 345 : 
FilterIndex 345 
Flags 345 
InitialDir 346 
destructor 345 
member functions 
- SetFilter 346 
TopLeft member function 
TRect 696 | 


_ TopRight member function 


TRect 696 
Touches member function 
TRect 696 
TRegion 387 
TOutStream class 346 
constructor 346 
TPaintDC class 347 
constructor 347 
data members — 
— Ps 347. 
Wnd 347 
destructor 347 


| TPalette class 347 


constructors 347 
member functions 
AnimatePalette 348 
Create 350 
GetNearestPaletteIndex 
348 : 
GetNumEntries 349 
GetObject 349 
GetPaletteEntries 349 
GetPaletteEntry 349 
ResizePalette 349 
SetPaletteEntries 349 
SetPaletteEntry 350 
ToClipboard 350 
UnrealizeObject 350 
operators 349 
TPaletteEntry class 350 
constructors 351 
TPen class 351 
constructors 351 
member functions 
GetObject 352 
operator 352 
TPicResult enum 353 
TPlacement enum 353 
TPoint class 686 
constructors 687 
member functions 
Offset 687 
OffsetBy 687 
operators 687, 688 
TPoint*() operator 
TRect 695 
TPointer<> class 689 
constructors 689 
operators 689 
TPopupMenu class 353 
constructor 353 
member functions 
TrackPopupMenu 353 
TPreviewPage class 354 
constructor 354 
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- data members 


PrintDC 355 

PrintExtent. 355 

Printout 355 
member functions 

EvSize 355 

Paint 355 

SetPageNumber 355 


TPrintDC class 356 


constructors 356 

member functions 
AbortDoc 356 
BandInfo 356 
DeviceCapabilities 356 
EndDoc 359 
EndPage 359 
Escape 359 
NextBand 362 
QueryAbort 362 
QueryEscSupport 363 
SetAbortProc 363 
SetCopyCount 363 
StartDoc 363 
StartPage 363 

structs 
DOCINFO 363 


TPrintDialog class 367 


constructor 368 

data members 
Data 368 
pd 368 

member functions 
CmSetup 369 
DialogFunction 369 
DoExecute 368 
GetDefaultPrinter 368 


TPrintDialog::TData struct 364 


data members 
Copies 364 
Error 364 
Flags 365 
FromPage 366 
‘MaxPage 366 
MinPage 366 
ToPage 366 
member functions 
ClearDevMode 366 
ClearDevNames 366 
GetDeviceName 367 
GetDevMode 367 
GetDevNames 367 
GetDriverName 367 
GetOutputName 367 
Lock 367 
SetDevMode 367 
SetDevNames 367 
TransferDC 367 
Unlock 367 


TPrinter class 369 
constructor 369 
data members 
BandRect 370 
Data 370 
Error 370 
FirstBand 370 
Flags 371 
PageSize 371 
UseBandInfo 371 
destructor 369 
error codes, returning 370 
member functions 
CalcBandingFlags 371 
ClearDevice 369 
CreateAbortWindow 371 
ExecPrintDialog 371 
GetDefaultPrinter 371 
GetSetup 369 
GetUserAbort 370 
Print 370 
ReportError 370 
SetPrinter 371 
Setup 370 
SetUserAbort 370 
TPrinter::TXPrinter class 372 
constructor 372 
TPrinterAbortDlg class 372 
constructor 372 
member functions 
EvCommand 372 
SetupWindow 372 
TPrintout class 373 
constructor 373 
data members 
Banding 375 
DC 375 
ForceAllBands 375 
PageSize 375 
destructor 373 
member functions 
BeginDocument 373 
BeginPrinting 373 
EndDocument 373 
EndPrinting 373 
GetDialogInfo 374 
GetTitle 374, 375 
HasPage 374 
PrintPage 374 
SetPrintParams 374 
WantBanding 374 
WantForceAllBands 374 
typedefs 375 
TPrintoutFlags enum. 375 
TPrintPreviewDC class 375 
-constructor 376 
data members 
CurrentPreviewFont 379 


GetAttributeHDC 379 
PrnDC 379 
PrnFont 379 
destructor 376 
member functions 
GetDeviceCaps 376 
LPtoSDP 376 


OffsetViewportOrg 376, 


378 
ReOrg 376 
ReScale 376 
RestoreFont 377 
ScaleViewportExt 377 
ScaleWindowExt 377 
SDPtoLP 377 
SelectObject 377 
SelectStockObject 377 
SetBkColor 378 
SetMapMode 378 
SetTextColor 378 
SetViewportExt 378 
SetWindowExt 378 
SyncFont 379 
TProclInstance class 690 
constructor 690 
destructor 690 
operator 690 
TProfile class 379 
constructor 379 
destructor 380 
member functions 
GetInt 380 
GetString 380. 
WriteInt 380 
WriteString 380 
TPXPictureValidator class 380 
constants 381 
constructor 380 » 
data members 
Pic 382 
member functions 
Error 381 
IsValid 381 
IsValidInput 381 
Picture 381 
TrackMenuSelection data 
member ; 
TDecoratedFrame 161 
TrackMode data member 
TScroller 395 
TrackMouse data member 
TGadget 233 
TrackPopupMenu member 
function 
TPopupMenu. 353 
TRadioButton class 382 
constructors 382 


member functions 
BNClicked 383 
GetClassName 383 
TRangeValidator class 383 
constructor 383 
data members 
Max 384 
Min 384 
member functions 
Error 383 
IsValid 383 
Transfer 384 
transfer buffers 485, 490 
transfer functions 432 
transfer mechanism 
buffers 490 
interface objects 
disabling 463 
enabling 464 
transfer mediums, 
registering 568 
Transfer member function 
TCheckBox 85 
TComboBox 106 
TEdit 198 
TListBox 270 
TRangeValidator 384 
TScrollBar 394 
TStatic 411 
TValidator 438 
TWindow 488 
TransferBuffer data member 
TWindow 490 
TransferData member function 
TInputDialog 256 
TWindow 488 
TransferDC member function 
TPrintDialog::TData 367 
Translate member function 
TLocaleString 278 
TranslateAccel member function 
TOcApp 605 
translating coordinate 
systems 310 
translating string resources 276 
TRect class 690 
constructors 691 
member functions 
Area 691 
BottomLeft 691 
BottomRight 692 
Contains 692 
Height 692 
Inflate 692 
InflatedBy 692 
IsEmpty 693 
IsNull 693 
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Normalize 693 
_ Normalized 693 
Offset 693 
OffsetBy 693 
Set 695 
SetEm ae 696 
SetNull 696 
Size 696 
TopLeft 696 
TopRight 696 
Touches 696 
Width 696 
operators 694 
TRegion class 384 
constructors 385 
member functions — 
Contains 385 
GetRgnBox 385 
SetRectRgn 387 
Touches 387 
operators 386, 387 
typedefs 384 
TRegistrar class 653 
data members 
AppDesc 657 
member functions 
CanUnload 654 
GetFactory 655 
GetOptions 655 
IsOptionSet 655 
ProcessCmdLine 656 
RegisterAppClass 656 
Run 656 
SetOption 657 
air 657 
UnregisterAppClass 657 
TRegList structure 683 


TRelationshipUnits enum 387 | 


TReplaceDialog class 387 
constructor 388 
member functions 

DoCreate 388 

TResId class 696 
constructors 697 
member functions 

IsString 697 
operators 697 
TResponseTableEntry class 388 
data members 
Dispatcher 388 
Id 388 
Msg 389 — 
NotifyCode 389 
Pmf 389 
typedets 389 

TRgbQuad class 389 

constructors 389 


TRgbQuad() operator 


TDib 174 
TRegbTriple class 390 
constructors 390 
try keyword 502 
TScreenDCE class 390 
constructors 391 
TScrollBar class 391 
constructors 391 
data members 
LineMagnitude 391 
PageMagnitude 391 
SetupWindow 394 
member functions 
DeltaPos 392 
EvHScroll 392 
EvVScroll 392 
GetClassName 394 
GetPosition 392 
GetRange 392 
SBBottom 392 
SBLineDown 392 
SBLineUp 393 
SBPageDown 393 
SBPageUp 393 


SBThumbPosition 393 


SBThumbTrack 393 
SBTop 393 
SetPosition 393 
SetRange 393 
Transfer 394 
warning 391 
TScrollBarData struct 394 
data members 
HighValue 394 
LowValue 395 
Position 395 — 
TScroller class 395 
constructor 396 
conversions 46 
data members 
AutoMode 395 
AutoOrg 395 
HasHScrollBar 395 
HasVScrollBar 395 
TrackMode 395 
Window 395 
XLine 396 
XPage 396 
XPos 396 
XRange 396 
XUnit 396 
YLine 396 
YPage 396 
YPos 396 
YRange 396 
— YUnit 396 
destructor 396 
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member functions 
AutoScroll 396 
BeginView 396 
~EndView 397 
HScroll 397 
IsAutoMode 397 
IsVisibleRect 397 — 
ScrollBy 398 
ScrollTo 398 
SetPageSize 397 
SetRange 397 

— SetSBarRange 397 
SetUnits 397 
SetWindow 398 
VScroll 398 
XRangeValue 398 
XScroliValue 398 
YRangeValue 398 
YScrollValue 398 


TSeparatorGadget class 398 


member functions 
TSeparatorGadget 399 


TSeparatorGadget member 
function : 


TSeparatorGadget 399 


TShadowStyle enum 75 
TSize class 697 


4 


constructors 698 
member functions 
Magnitude 698 


- operators 698, 699 
TSlider class 399 


constructors 400 

data members 
Bkcolor 404. 
CaretRect 404 
Max 404 
Min 404 
MouseOffset 404 
Pos 404 
Range 404 
SlideDC 404 
Sliding 404 
SlotThick 404 
Snap 405 
ThumbRect 405 
ThumbResId 405 
TicGap 405 

destructor 400 

member functions 
EvEraseBkgnd 401 
EvGetDlgCode 401 
EvKeyDown 401 
EvKillFocus 401 
EvLButtonDbIiClk 402 
EvLButtonDown 402 
EvLButtonUp 402 
EvMouseMove 402 


EvPaint 402 
EvSetFocus 402 
EvSize 402 
GetBkColor 402 
GetPosition 400 
GetRange 400 
HitTest 402 
NotifyParent 403 
PaintRuler 403 
PaintSlot 403 
PaintThumb 403 
PointToPos 403 
PosToPoint 403 
SetPosition 400 
SetRange 400 
SetRuler 400 


SetupThumbRegn 403, 405 


SetupWindow 403 
SlideThumb 403 
SnapPos 404 


TSortedStringArray class 408 


constructor 408 

member functions 
Add 408 
ArraySize 408 
Destroy 409 
Detach 409 
Find 409 
FirstThat 409 
Flush 409 
ForEach 409 


GetItemsInContainer 409 


HasMember 409 
IsEmpty 409 
IsFull 410 
LastThat 410 
LowerBound 410 
UpperBound 410 
operator 410 
typedefs 408 
TState enum 75 
TState member function 
TButtonGadget 75 
TStatic class 410 
constructors 411 
member functions 
Clear 411 
EvSize 412 
GetClassName 412 
GetText 411 
GetTextLen 411 
SetText 411 
TextLen 410 
Transfer 411 
TStatus class 412 
constructor 412 
operators 412 
TStatusBar class 413 
constructor 414 


data members 
BorderStyle 415 
ModelIndicators 415 


ModelndicatorState 415 
NumModelndicators 415 


Spacing 415 
member functions 


GetModelndicator 414 


IdleAction 415 
Insert 414 
PositionGadget 416 
PreProcessMsg 416 


SetModelIndicator 414 


SetSpacing 414 


ToggleModelndicator 415 


operators 414 

typedefs 413 
TStatusBar enum. 413 
TStgDocProp enum 416 


TStorageDocument class 416 


constructor 417 

data members 
Storagel 420 
ThisOpen. 420 

destructor 417 

member functions 
Close 417 
Commit 417 
FindProperty 418 
GetProperty 418 
GetStorage 418 
InStream 418 
IsOpen 418 
Open. 418 : 
OpenHandle 418 
OutStream 419 
PropertyCount 419 
PropertyFlags 419 
PropertyName 419 
ReleaseDoc 419 
Revert 419 
SetDocPath 419 
SetProperty 419 
SetStorage 420 

typedefs 416 

TStream class 420 

constructor 421 

data members 
Doc 421 
NextStream 421 

destructor 420 

member functions 
GetDocument 420 
GetOpenMode 420 
GetStreamName 421 

TStringLookup Validator 
class 421 
constructor 421 


data members 
Strings 422 
destructor 421 
member functions 
Error 422 
Lookup 422 
NewstringList 422 
TStyle enum. 433 
TSystemMenu class 422 
constructor 422 
TTextGadget class 422° 
constructor 423 
data members 
Align 423 
NumcChars 423 
Text 423 
TextLen 423 
destructor 423 
member functions 
GetDesiredSize 423 
GetText 423 
Invalidate 424 
Paint 424 
SetText 423 
TAlign 424 
typedefs 424 
TTileDirection enum 424 
TTinyCaption class 424 
constructor 426 
data members 
Border 425 © 
CaptionFont 425 
CaptionHeight 425 
CloseBox 425 
DownHit 425 
Frame 426 
IsPressed 426 
TCEnabled 426 


WaitingForSysCmd 426 


destructor 426 

member functions 
DoCommand 426 
DoLButtonUp 426 
DoMouseMove 426 
DoNCActivate 427 
DoNCCalcSize 427 
DoNCHitTest 427 


DoNCLButtonDown 427 


DoNCPaint 427 
DoSysCommand. 427 
DoSysMenu 427 
EnableTinyCaption 427 
EvCommand 428 
EvLButtonUp 428 
EvLMouseMove 428 
EvNCActivate 428 
EvNCCalcSize 428 
EvNCHitTest 428 


index 


~ EvNCLButtonDown 429 


EvPaint 429 
EvSysCommand. 429 
GetCaptionRect 429 
GetMaxBoxRect 429 
GetMinBoxRect 429 
GetSysBoxRect 429 
PaintButton 429 
PaintCaption 429 
PaintCloseBox 430 
PaintMaxBox 430 
PaintMinBox 430 
PaintSysBox 430 
TToolBox class 430 

constructor 431 

- data members 
NumColumns 431 
NumRows 431 
TileGadgets 432 

member functions _ 
GetDesiredSize 431 
Insert 431 
LayoutSession 431 
SetDirection 431 


TTransferDirection enum 432 . 


TType enum 75, 246 
TUlIHandle class 432 
constructor 435 

member functions 


GetBoundingRect 435 


GetCursorld 435 
HitTest 435 
Move 435 
MoveTo 436 
Paint 436 
Size 436— 
typedefs 433, 434 
TUnknown class 658 
~ constructor 659 
data members 
Outer 660 
destructor 659 
member functions 
Aggregate 658 
GetOuter 658 
GetRefCount 659 
QueryObject 660 
SetOuter 659 
ThisUnknown 660 
operators 659 
TUString*() operator 
TAutoVal 598 
TValidator class 436 
constructor 437 
data members 
Options 439 
destructor 437 


member functions 
Error 437 
HasOption 437 
IsValid 438 
IsValidInput 438 
SetOption 438 
Transfer 438 
UnsetOption 439 
ariel 
TXValidator class 440 
typedefs 439 
TValidatorOptions class 
typedefs 439 
TVbxControl class 440 © 
constructors 441 
destructor 442 
member functions 
AddItem 442 
Drag 442 
GetClassName 446 
GetEventIndex 442 
GetEventName 442 — 
GetHCTL 442 
GetNumEvents 442 
GetNumProps 442 
GetProp 442 
GetPropIndex 443 
_ GetPropName 444 
~GetPropType 444 
GetVBXProperty 446 
IsArrayProp 444 
Method 444 
Move 444 | 
PerformCreate 446 
Refresh 444 
Removeltem 445 
SetProp 445 
SetpWindow 446 
SetVBXProperty 446 


TVbxEventHandler class 447 


member functions _ 

EvVbxDispatch 451 
TView class 451 

constructor 452 

data members 
Doc 454 
Tag 452 

destructor 452 

enums 452 

member functions 
FindProperty 452 
GetDocument 452 
GetNextViewld 452 
GetProperty 452 
GetViewld 453 
GetViewMenu 453 
GetViewName 453 
GetWindow 453 
IsOK 453 
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NotOK 454 
PropertyCount 453 
PropertyFlags 453 
PropertyName 453 
~ SetDocTitle 453 
SetProperty 454 
SetViewMenu 454 


_TVSlider class 407 


constructor 407 
member functions 
HitTest 407 
NotifyParent 407 
PaintRuler 407 
PaintSlot 407 
PointToPos 407 
PosToPoint 408 
TWhere enum 434 _ 
TWidthHeight enum 454 


‘TWindow class 454 


attribute masks 496-497 
constants 496 
constructors 491 
data members 
Attr 455 
BkgndColor 489 
CursorModule 490 
CursorResId 490 
DefaultProc 456 
hAccel 490 
HCursor 490 
HWindow 456 
Parent 456 
Scroller 456 
Status 456 
Title 456 
TransferBuffer 490 
destructor 457 
flag constants 459 
ForEach member function 
TActionFunc typedef 51 . 
TMemFunc typedef 51 — 
member functions 114 
AdjustWindowRect 457 
AdjustWindowRectEx 457 
BringWindowToTop 458 
CanClose 458 
CheckDlgButton 459 
CheckRadioButton 459 — 
ChildBroadcastMessage 
459 | 
ChildWindowFromPoint 
459 | 
ChildWithId 459 
CleanupWindow 491 
ClearFlag 459 
ClientToScreen 459 
CloseWindow 459 
CmExit 460 © 
Create 460 


CreateCaret 460 
CreateChildren 460 
DefaultProcessing 460 
defining 114 
DefWindowProc 463 
Destroy 463 
DestroyCaret 463 
DisableAutoCreate 463 
DisableTransfer 463 
Dispatch 463 
DispatchScroll 491 
DragAcceptFiles 464 
DrawMenuBar 464 
EnableAutoCreate 464 
EnableScrollBar 155, 464 
EnableTransfer 464 
EnableWindow 464 
EnumProps 464 
EvChildInvalid 464 

- EvCommand 465 
EvCommandEnable 465 
EvSysCommand 465 
FirstThat 466 
FlashWindow 466 
ForEach 466 
ForwardMessage 467 
GetActiveWindow 467 
GetApplication 467 
GetCapture 467 
GetCaretBlinkTime 467 
GetCaretPos 467 
GetClassLong 468 
GetClassName 491 
GetClassWord 468 
GetClientRect 468 
GetCursorPos 468 
GetDesktopWindow 469 — 
GetDlgCtrHD 469 
GetDlgItem 469 
GetDlgItemInt 469 
GetDlgItemText 469 
GetFirstChild 469 
GetFocus 469 
GetHWndState 469 
GetlId 469 
GetLastActivePopup 470 
GetLastChild 470 
GetMenu 470 
GetModule 470 
GetNextDlgGroupItem 


GetTopWindow 472 
GetUpdateRect 472 
GetUpdateRgn 472 
GetWindow 472 
GetWindowClass 491 
GetWindowFont 472 
GetWindowLong 472 
GetWindowPlacement 473 
GetWindowPtr 470 
GetWindowRect 473 
GetWindowTask 473 
GetWindowText 473 
GetWindowTextLength 
473 
GetWindowTextTitle 474 
GetWindowWord 474 
HandleMessage 474 
HideCaret 474 
HiliteMenultem 474 
HoldFocusHwnd 475 
IdleAction 475 
Init 493 
Invalidate 475 
InvalidateRect 475 
InvalidateRgn 475 
IsChild 476 
IsDlgButtonChecked 476 
IsFlagSet 476 
IsIconic 476 
IsWindow 476 
IsWindowEnabled 476 
IsWindow Visible 476 
IsWindowZoomed 476 
KillTimer 476 
LoadAcceleratorTable 493 
LockWindowUpdate 477 
MapWindowPoints 477 
MessageBox 477 
MoveWindow 477 
Next 478 
NumChildren 478 
OpenClipboard 478 
Paint 478 
PerformCreate 478 
PostMessage 478 
PreProcessMsg 478 
Previous 479 
ReceiveMessage 479 
RedrawWindow 479 
Register 480 


SetActiveWindow 481 
SetBkgndColor 482 
SetCaption 482 
SetCapture 482 
SetCaretBlinkTime 482 
SetCaretPos 482 
SetClassLong 482 
SetClassWord 482 
SetCursor 483 
SetDlgltem 483 
SetDigItemText 483 
SetDocTitle 483 
SetFlag 483 

SetFocus 484 
SetMenu 484 
SetModule 484 
SetNext 484 
SetParent 484 

SetProp 484 
SetRedraw 484 
SetScrollPos 485 
SetScrollRange 485 
SetSysModalWindow 485 
SetTimer 485 
SetTransferBuffer 485 


SetupWindow 493 


SetWindowFont 485 
SetWindowLong 485 
SetWindowPlacement 486 
SetWindowPos 486 
SetWindowText 486 
SetWindowWord 487 
Show 487 
ShowCaret 487 
ShowOwnedPopups 487 
ShowScrollBar 487 
ShowWindow 487 
ShutDownWindow 487 
SubclassWindow Function 
488 
Transfer 488 
TransferData 488 
UnregisterHotKey 488 
UpdateWindow 488 
Validate 488 
ValidateRect 488 
ValidateRgn 489 
WindowFromPoint 489 
WindowProc 489 
WinHelp 489 


470 RegisterHotKey 480 


operators 475 
GetNextDlgTabltem 470 ReleaseCapture 480 


TWindowdAttr struct 455, 494 


GetNextWindow 470 RemoveChild 493 . data members 
GetParent 471 RemoveProp 480 AccelTable 495 
GetProp 471 ScreenToClient 480 ExStyle 495 
GetScrollPos 471 ScrollWindow 481 H 496 
GetScrollRange 471 ScrollWindowEx 481 _ Id 495 
GetSysModalWindow 471 SendDlglItemMessage 481 Menu 495 
GetSystemMenu 471 SendMessage 481 Param 495 


GetThunk 471 SendNotification 481 
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Style 495 
W 496 
X 496 
Y 496 
style constants 495 
TMenu resource ID 495 
TWindowDC class 497 
constructors 497 
data members 
Wnd 497 
destructors 497 
TWindowFlag enum 496 
TWindowView class 498 
constructor 498 
destructor 498 
member functions 
CanClose 498. 
GetViewName 498 
GetWindow 498 
SetDocTitle 499 
StaticName 499 
TWindow::TXWindow class 499 
TxXAuto class 660 
constructor 660 
data members 
ErrorCode 661 
type definitions 
TError enum 661 
TXAuto exception 588, 589 
TXAuto::xTypeMismatch 
exception 584 
TXBase class 699 
constructor 700 
data members 
- InstanceCount 700 
destructor 700 
member functions 
Clone 700 
Throw 700 
TXCompatibility class 500 
member functions 
Clone 500 
MapStatusCodeToString 
500 
Throw 500 
Unhandled 501 
TXCompatibility exception 304, 
412 
TXGdi nested class 250 
constructor 500 
TXInvalidMainWindow class 63 
TXInvalidMainWindow 
exception 62 
TXInvalidModule exception 307 
TXInvalidModule nested 
class 310 
constructor 310 


member functions 
Clone 310 
Throw 310 
TXInvalidWindow 
exception 273 
TXMenu class 501 
constructor 501 
member functions 
Clone 501 
Throw 501 
TXObjComp class 661 
constructor 662 
data members 
ErrorCode 662 
type definitions 
TError enum. 662 
TXObjComp exception 637 
TXOle class 662 | 
constructors 663 
data members 
Stat 664 
destructors 663 
member functions 
Check 663 
TXOle exception 587 
TXOutOfMemory class 501 
constructor 501 
member functions 
Clone 501 
Throw 502 
TXOw1 class 502 
constructors 503 
data members 
ResId 503 
destructor 503 
member functions 
Clone 504 
GetErrorCode 504 
ResourceldToString 504 
Throw 504 
Unhandled 504 
TXPrinter nested class 372 
TXRegistry class 664 
constructors 664 
data members 
Key 665 
member functions 
Check 664 
TXValidator class 440 
constructor 440 
TXWindow class 499 
constructors 499 
data members 
Window 499 
member functions 
Clone 499° | 
Msg 500 
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Throw 500 
Unhandled 500 
message constants 43 
type checking 577, 578, 580, 590 
Type data member 
TButtonGadget 77 
type definitions 
TAppDictionary class 53 
TApplication class 56 
TButtonGadget 75 
TCommandEnabler class 111 
TDecoratedFrame class 160 
TDib class 169 
TDocument class 183 
TFileDocument class 211 
TGadgetWindow class 236 
TLangld 686 
TMenuDescr class 296 
TRegion class 384 
TResponseTableEntry 
class 389 
TSortedStringArray class 408 
TStatusBar class 413 
TTextGadget class 424 
TUlIHandle class 433 
TValidator class 439 
typecasting pointers 555, 584 
typehelp registration key 665 
TypeName data member 
TOcVerb 644 
TYPEREAD utility 528 
typographical conventions 3 


U 


U_Dispatch function 515 
U_LPARAM_Dispatch 
function 516 
U_POINT_Dispatch 
function 516 | 
U_U_Dispatch function 516 
U_U_U_U_Dispatch 
function 516 
U_WPARAM_LPARAM 
_Dispatch function 516 
Ul grapples 432 
Ulhandles 432 
uihandle.h 23 
uint() operator 
TMenu 292 
Unbind member function 
TAutoEnumerator 580 
TAutoProxy 589 
Uncheck member function 
TCheckBox 85 | 
Uncondemn member function 
TApplication 61 


Undo member function 
TAutoCommand 577 
TEdit 198 

undo stack 577 
automation 548 

Unhandled member function 
TXCompatibility 501 
TXOwl1 504 
TXWindow 500 

Units data member 
TLayoutConstraint 258 

Unlock member function 
TPrintDialog::TData 367 

UnlockBuffer member function 
TEdit 198 

UnrealizeObject member 

function 
TBrush 72 
TPalette 350 
UnRefTemplate member 
function 
TDocManager 181 
UnregisterAppClass member 
function 
TRegistrar 657 
UnregisterClass member 
function 
TOcApp 605 
UnregisterClasses member 
function 
TOcApp 606 
UnregisterHotKey member 
function 
TWindow 488 

UnsetOption member function 
TValidator 439 

unsigned long far*() operator 
TAutoVal 598 

unsigned long() operator 
TAutoVal 598 

Update member function 
TControlGadget 117 
TGadget 234 

update rectangle, windows 472 

update region, windows 472 

UpdateColors member function 
TDC 157 

UpdateRect member function 
TOcPart 631 

UpdateWindow member 

function 
TWindow 488 

UpperBound member function 
TSortedStringArray 410 

Usage member function 
TDib 174 


usage registration key 570, 665 
UseBandInfo data member 
TPrinter 371 
user input 
checking 215, 278 
data entry 436 
input fields 421 
numeric values 383 
picture strings 380 
retrieving 255 
user interface 
See also interface objects 
bitmaps 80 


V 


v_Activate_Dispatch 
function 516 
v_Dispatch function 517 
v_LPARAM_Dispatch 
function 517 
v_MdiActivate_Dispatch 
function 517 
v_ParentNotify_Dispatch 
function 517 
v_POINT_Dispatch function 517 
v_POINTER_Dispatch 
function 517 
v_U_Dispatch function 517 
v_U_POINT_Dispatch 
function 518 
v_U_U_Dispatch function 518 
v_U_U_U_Dispatch 
function 518 
v_U_U_W_Dispatch 
function 518 
v_WPARAM_ Dispatch 
function 518 
v_WPARAM_LPARAM 
_Dispatch function 518 
valid characters 
input fields 215 
picture formats 381 
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TValidator 439 
Validate member function 
TAutoCommand 577 
TWindow 488 
VALIDATE.CPP 436 
validate.h 23. 
ValidateRect member function 
TWindow 488 
ValidateRgn member function 
TWindow 489 | 
validating edits 197 
validating pictures 353 


validating user input 215, 278 
data entry 436 
input fields 421 
numeric values 383 
picture strings 380 
Validator data member 
-‘TEdit 198 
ValidatorError member function 
TEdit 198 
validators 
data transfer 384, 438 
filter 215 
IDs 44 
lookup 278 
string 421 
picture 380 
range 383 
validity testing 215, 422 
picture formats 381 
ValidChars data member 
TFilterValidator 215 
validity testing 438, 439 
ValidWindow member function 
TModule 309. 
Value constant 258 
Value data member 
TColor 101 
TGauge 244 
Value member function 
TAutoEnumerator 580 
values 
checking 438 
range of 383 
setting 215 
maximum/minimum 384 
VARIANT data type 594 
VBX controls 440 
VBX events 447 
vbxctLh 23 
VerbIndex data member 
TOcVerb 645 
verbn registration keys 665 
VerbName data member 
TOcVerb 645 
verbnopt registration keys 666 
verbs 644 
enumerating 627 
executing 627 
verifying registration 634 
version numbers, returning 50 
version registration key 666 
version.h 23 
vertical scroll bars 391 
vertical sliders 407 
view event messages 565 
view notification constants 504 
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viewing 

current state, program 413, 

415 | | 

data 536 

objects 536 
viewport 376, 377,378 
viewport coordinates 310 
views 

closing 34 

creating 34, 182 

destroying 182 

event tables 183 

ID constants 43 

with no window 451 
virtual function tables 50 
vnCommit constant 504 
VnCommit member function 

TEditView 207 

TListView 275 
vnCustomBase constant 504 
vnDocClosed constant 504 
VnDocClosed member function 

TEditView 208 

TListView 275 
vnDocOpened constant 504 
vniInvalidate constant 504 
VnInvalidateRect member 

function 

TOleView class 326 

TOleWindow 340 
vnisDirty constant 504 
VnisDirty member function 

TEditView 208 

TListView 275 
vnisWindow constant 504 
VnIsWindow member function 

TEditView 208 

TListView 275 
vnRevert constant 504 
VnRevert member function 

TEditView 208 

TListView 276 
vnViewClosed constant 504 
vnViewOpened constant 504 
voFill constant 439 
void pointers 564 
void typedef 408 
voOnAppend constant 439 
voReserved constant 439 
voTransfer constant 439 
VScroll member function 

TScroller 398 


W 


W data member 
TDib 175 | 
TWindowAttr 496° 
WaitingForSysCmd data 
member 
TTinyCaption 426 
WantBanding member function 
TPrintout 374 
WantForceAllBands member 
function 
TPrintout 374 
warning beeps 200 
wfAlias constant 496 
wfAutoCreate constant 460, 496 
wfFromResource constant 497 
wiFullyCreated constant 497 
wfMainWindow constant 497 
wfPredefinedClass constant 497 
wfShrinkToClient constant 497 
wiStreamTop constant 497 
wfIransfer constant 497 
wfUnDisabled constant 497 
wfUnHidden constant 497 
Where data member 
TOcDragDrop structure 613 
TOcInitInfo 619 
White data member 
TColor 100 
WideAsPossible data member 
TGadget 229 
TGadgetWindow 240 
WidenPath member function 
TDC 157 
widgets 12 
width, rectangles 698 
Width data member 
TLayoutMetrics 259 
TOcMenuDescr structure 622 


~Width member function 


TBitmap 67 
TDib 174 
TMetaFilePict 303 
TRect 696 
Win data member 
TOcView 651 
Win32, icons 3 
WIN32 DLLs 
building 50 
exporting 49 
importing 49 
window classes 11 
returning information on 306 
Window data member 
TGadget 233 
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TScroller 395 
TXWindow 499 
window mapping 
functions 376, 377, 378 
window.h 23 
windowev.h 23 a 4 
WindowFromPoint member 
function | 
TWindow 489 
WindowProc member function 
TWindow 489 
windows 432 
bit mask constants 496 
caption bars, creating 424 
cascading 282 
child 162, 256, 258, 279, 281, 
282 
client 159, 222 
Clipboard-viewer chain 
adding 96, 98 
removing 98 
closing 57, 282, 459, 460 
| dialog box 164, 165 
constraints 
defined 258 
edge 190, 258, 261 
layout 256, 258 
coordinate systems, 
translating 310 
creating 165, 256, 454 
| main 55, 62 
decorating 159, 162 
default procedure 456 
default processing 162 
handles, retrieving 94,95 
layout 387 
constraints 256, 258 
metrics, defining 258, 261 
main See main window 
moving through 222 
naming 62, 456, 474 
painting 226 
placing 190 
property list, retrieving 
handle for 471 
scaling 311 
scrolling 311, 642 
sizing, 286, 387, 454 
tiling 283 
Windows applications 
bitmaps, predefined 307 
control message 167 
CTL3D DLL support 163 
cursors, predefined 308 
default message 
processing 456 
handles, returning 309 


icons, predefined 308 
interface element 460 
radio button interface 
element 382 
redisplay 478 
registration class 
attributes 491 
registration class name 85, 
251, 412, 491, 480 
resources, loading into 
memory 309 
Windows functions 701, 707 
WinHelp member function 
TWindow 489 
WinTitle data member 
TOcView 651 
WM_CREATE message 495 
WM_INITDIALOG 
message 169 
WM_OCEVENT message 667 
WM_PAINT message 226, 478 
WM_ITIMER messages 476, 485 
Wnd data member 
TPaintDC 347 
TWindowDC 497 
WNDCLASS struct 736 
word-break functions 198 
wordwrapping 194, 196 
WParam parameter 167 
Write member function 
TEditFile 203 
TOleDocument 314 
WriteFile member function 
TDib 174 
WriteInt member function 
TProfile class 380 
WriteString member function 
TProfile class 380 
WS_ window style 
constants 102, 118, 382, 411 
WS_BORDER constant 265, 495 
WS_CAPTION constant 495 
WS_CHILD constant 495 
WS_CHILDWINDOW 
constant 495 
WS_CLIPCHILDREN 
constant 495 
WS_CLIPSIBLINGS 
constant 495 
WS_DISABLED constant 496 
WS_DLGFRAME constant 496 
WS_GROUP constant 496 
WS_HSCROLL constant 391, 
496 
WS_MAXIMIZE constant 496 


WS_MAXIMIZEBOX 
constant 496 

WS _MINIMIZE constant 496 

WS_ OVERLAPPED 
constant 496 

WS_OVERLAPPEDWINDOW 
constant 496 | 

WS_POPUFP constant 496 

WS_POPUPWINDOW 
constant 496 

WS _SYSMENU constant 496 

WS_TABSTOP constant 496 

WS_TABSTOP style 251 

WS_THICKFRAME 
constant 496 

WS VISIBLE constant 496 

WS _VSCROLL constant 265, 
391, 496 | 


X 


X data member 
TLayoutMetrics 259 
TWindowAttr 496 

xConversionFailure 

exception 594 

XFORM struct 739 

XLine data member 
TScroller 396 

xmsg exception 305 

xNoArgSymbol exception 591 

XPage data member 
TScroller 396 

XPos data member 
TScroller 396 

XRange data member 
TScroller 396 

XRangeValue member function 
TScroller 398 

xs exception status bit flags 61 

xs exception status enum 56 

xsAlloc constant 56 

xsBadCast constant 56 

xsBadTypeid constant 56 

XScrollValue member function 
TScroller 398 

xsMsg constant 56 

xsOwl constant 56 

xsUnknown constant 56 

XUnit data member 
TScroller 396 


Y 


Y data member 
TLayoutMetrics 259 
TWindowAttr 496 

YLine data member 
TScroller 396 

YPage data member 
TScroller 396 

YPos data member 
TScroller 396 

YRange data member 
TScroller 396 

YRangeValue member function 
TScroller 398 

YScrollValue member function 
TScroller 398 

YUnit data member 
TScroller 396 
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